diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ab25cbe972..7243146d5d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -76,8 +76,12 @@ jobs: - uses: actions/checkout@v4 - name: Install Dependencies run: | - sudo apt-get update - sudo apt-get install libsdl2-dev + curl -LO https://github.com/libsdl-org/SDL/releases/download/release-3.2.20/SDL3-3.2.20.tar.gz + tar zxf SDL3-3.2.20.tar.gz + cd SDL3-3.2.20 + cmake -S . -B build + cmake --build build + sudo cmake --install build - name: Compile run: | cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release @@ -173,10 +177,18 @@ jobs: - name: Install emsdk uses: mymindstorm/setup-emsdk@v13 with: - version: 3.1.58 + version: 4.0.11 + - name: Install Dependencies + run: | + curl -LO https://github.com/libsdl-org/SDL/releases/download/release-3.2.20/SDL3-3.2.20.tar.gz + tar zxf SDL3-3.2.20.tar.gz + cd SDL3-3.2.20 + emcmake cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/sdl3-emscripten-install + cmake --build build + sudo cmake --install build - name: Compile run: | - emcmake cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + emcmake cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DSDL3_DIR="$HOME/sdl3-emscripten-install/lib/cmake/SDL3" cmake --build build - name: Upload uses: actions/upload-artifact@v4 @@ -189,6 +201,14 @@ jobs: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 + - name: Install SDL + run: | + curl -LO https://github.com/libsdl-org/SDL/releases/download/release-3.2.20/SDL3-3.2.20.tar.gz + tar zxf SDL3-3.2.20.tar.gz + cd SDL3-3.2.20 + cmake -S . -B build + cmake --build build + sudo cmake --install build - name: Install Dependencies run: | sudo apt-get update @@ -207,7 +227,14 @@ jobs: uses: vmactions/freebsd-vm@v1 with: prepare: | - pkg install -y cmake ninja devel/sdl20 + pkg install -y cmake ninja + pkg install -y curl xorgproto libX11 libXext libXrandr libXcursor libXinerama libXi + curl -LO https://github.com/libsdl-org/SDL/releases/download/release-3.2.20/SDL3-3.2.20.tar.gz + tar zxf SDL3-3.2.20.tar.gz + cd SDL3-3.2.20 + cmake -S . -B build + cmake --build build + cmake --install build run: | cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build @@ -220,7 +247,14 @@ jobs: uses: vmactions/openbsd-vm@v1 with: prepare: | - pkg_add cmake ninja sdl2 + pkg_add cmake ninja + pkg_add curl + curl -LO https://github.com/libsdl-org/SDL/releases/download/release-3.2.20/SDL3-3.2.20.tar.gz + tar zxf SDL3-3.2.20.tar.gz + cd SDL3-3.2.20 + cmake -S . -B build + cmake --build build + cmake --install build run: | cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build diff --git a/cmake/libraries/sdl.cmake b/cmake/libraries/sdl.cmake index 4cd0b2991c..4318e4ee19 100644 --- a/cmake/libraries/sdl.cmake +++ b/cmake/libraries/sdl.cmake @@ -4,12 +4,12 @@ endif() if(EMSCRIPTEN) # Emscripten provides its own self contained SDL setup - list(APPEND CLIENT_COMPILE_OPTIONS -sUSE_SDL=2) - list(APPEND CLIENT_LINK_OPTIONS -sUSE_SDL=2) + list(APPEND CLIENT_COMPILE_OPTIONS -sUSE_SDL=3) + list(APPEND CLIENT_LINK_OPTIONS -sUSE_SDL=3) return() endif() -set(INTERNAL_SDL_DIR ${SOURCE_DIR}/thirdparty/SDL2-2.32.8) +set(INTERNAL_SDL_DIR ${SOURCE_DIR}/thirdparty/SDL3-3.2.18) include(utils/arch) @@ -19,7 +19,7 @@ if(WIN32 OR APPLE) endif() if(USE_INTERNAL_SDL AND HAVE_INTERNAL_SDL) - set(SDL2_INCLUDE_DIRS ${INTERNAL_SDL_DIR}/include) + set(SDL3_INCLUDE_DIRS ${INTERNAL_SDL_DIR}/include) list(APPEND CLIENT_DEFINITIONS USE_INTERNAL_SDL_HEADERS) list(APPEND RENDERER_DEFINITIONS USE_INTERNAL_SDL_HEADERS) @@ -33,32 +33,29 @@ if(USE_INTERNAL_SDL AND HAVE_INTERNAL_SDL) endif() if(MINGW) - set(SDL2_LIBRARIES - ${LIB_DIR}/libSDL2main.a - ${LIB_DIR}/libSDL2.dll.a) + set(SDL3_LIBRARIES + ${LIB_DIR}/libSDL3.dll.a) elseif(MSVC) - set(SDL2_LIBRARIES - ${LIB_DIR}/SDL2main.lib - ${LIB_DIR}/SDL2.lib) + set(SDL3_LIBRARIES + ${LIB_DIR}/SDL3.lib) endif() - list(APPEND CLIENT_DEPLOY_LIBRARIES ${LIB_DIR}/SDL2.dll) + list(APPEND CLIENT_DEPLOY_LIBRARIES ${LIB_DIR}/SDL3.dll) elseif(APPLE) - set(SDL2_LIBRARIES - ${SOURCE_DIR}/thirdparty/libs/macos/libSDL2main.a - ${SOURCE_DIR}/thirdparty/libs/macos/libSDL2-2.0.0.dylib) + set(SDL3_LIBRARIES + ${SOURCE_DIR}/thirdparty/libs/macos/libSDL3.dylib) list(APPEND CLIENT_DEPLOY_LIBRARIES - ${SOURCE_DIR}/thirdparty/libs/macos/libSDL2-2.0.0.dylib) + ${SOURCE_DIR}/thirdparty/libs/macos/libSDL3.dylib) else() message(FATAL_ERROR "HAVE_INTERNAL_SDL set incorrectly; file a bug") endif() else() - find_package(SDL2 REQUIRED) + find_package(SDL3 REQUIRED) endif() -list(APPEND CLIENT_LIBRARIES ${SDL2_LIBRARIES}) -list(APPEND CLIENT_INCLUDE_DIRS ${SDL2_INCLUDE_DIRS}) -list(APPEND CLIENT_COMPILE_OPTIONS ${SDL2_CFLAGS_OTHER}) -list(APPEND RENDERER_LIBRARIES ${SDL2_LIBRARIES}) -list(APPEND RENDERER_INCLUDE_DIRS ${SDL2_INCLUDE_DIRS}) -list(APPEND RENDERER_COMPILE_OPTIONS ${SDL2_CFLAGS_OTHER}) +list(APPEND CLIENT_LIBRARIES ${SDL3_LIBRARIES}) +list(APPEND CLIENT_INCLUDE_DIRS ${SDL3_INCLUDE_DIRS}) +list(APPEND CLIENT_COMPILE_OPTIONS ${SDL3_CFLAGS_OTHER}) +list(APPEND RENDERER_LIBRARIES ${SDL3_LIBRARIES}) +list(APPEND RENDERER_INCLUDE_DIRS ${SDL3_INCLUDE_DIRS}) +list(APPEND RENDERER_COMPILE_OPTIONS ${SDL3_CFLAGS_OTHER}) diff --git a/code/client/cl_main.c b/code/client/cl_main.c index 7cb92f6c12..4aeadf182d 100644 --- a/code/client/cl_main.c +++ b/code/client/cl_main.c @@ -3273,7 +3273,7 @@ void CL_InitRef( void ) { Com_Error(ERR_FATAL, "Failed to load renderer"); } - GetRefAPI = Sys_LoadFunction(rendererLib, "GetRefAPI"); + GetRefAPI = (GetRefAPI_t)Sys_LoadFunction(rendererLib, "GetRefAPI"); if(!GetRefAPI) { Com_Error(ERR_FATAL, "Can't load symbol GetRefAPI: '%s'", Sys_LibraryError()); diff --git a/code/client/keycodes.h b/code/client/keycodes.h index d0a188e65e..6bb851d5d3 100644 --- a/code/client/keycodes.h +++ b/code/client/keycodes.h @@ -294,6 +294,11 @@ typedef enum { K_PAD0_PADDLE3, /* Xbox Elite paddle P2 */ K_PAD0_PADDLE4, /* Xbox Elite paddle P4 */ K_PAD0_TOUCHPAD, /* PS4/PS5 touchpad button */ + K_PAD0_MISC2, /**< Additional button */ + K_PAD0_MISC3, /**< Additional button */ + K_PAD0_MISC4, /**< Additional button */ + K_PAD0_MISC5, /**< Additional button */ + K_PAD0_MISC6, /**< Additional button */ // Pseudo-key that brings the console down K_CONSOLE, diff --git a/code/renderercommon/qgl.h b/code/renderercommon/qgl.h index 512cdefcb0..78e8e959e1 100644 --- a/code/renderercommon/qgl.h +++ b/code/renderercommon/qgl.h @@ -27,9 +27,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #define __QGL_H__ #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL_opengl.h" +# include "SDL3/SDL_opengl.h" #else -# include +# include #endif extern void (APIENTRYP qglActiveTextureARB) (GLenum texture); diff --git a/code/renderergl2/tr_extensions.c b/code/renderergl2/tr_extensions.c index b8efe6a56d..92e5682bbb 100644 --- a/code/renderergl2/tr_extensions.c +++ b/code/renderergl2/tr_extensions.c @@ -22,9 +22,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA // tr_extensions.c - extensions needed by the renderer not in sdl_glimp.c #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" +# include "SDL3/SDL.h" #else -# include +# include #endif #include "tr_local.h" diff --git a/code/sdl/sdl_gamma.c b/code/sdl/sdl_gamma.c index 1fe4c4b147..2011bed9b6 100644 --- a/code/sdl/sdl_gamma.c +++ b/code/sdl/sdl_gamma.c @@ -21,9 +21,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" +# include "SDL3/SDL.h" #else -# include +# include #endif #include "../renderercommon/tr_common.h" @@ -38,48 +38,7 @@ GLimp_SetGamma */ void GLimp_SetGamma( unsigned char red[256], unsigned char green[256], unsigned char blue[256] ) { - Uint16 table[3][256]; - int i, j; - - if( !glConfig.deviceSupportsGamma || r_ignorehwgamma->integer > 0 ) - return; - - for (i = 0; i < 256; i++) - { - table[0][i] = ( ( ( Uint16 ) red[i] ) << 8 ) | red[i]; - table[1][i] = ( ( ( Uint16 ) green[i] ) << 8 ) | green[i]; - table[2][i] = ( ( ( Uint16 ) blue[i] ) << 8 ) | blue[i]; - } - -#ifdef _WIN32 - // Windows puts this odd restriction on gamma ramps... - ri.Printf( PRINT_DEVELOPER, "performing gamma clamp.\n" ); - for( j = 0 ; j < 3 ; j++ ) - { - for( i = 0 ; i < 128 ; i++ ) - { - if( table[ j ][ i ] > ( ( 128 + i ) << 8 ) ) - table[ j ][ i ] = ( 128 + i ) << 8; - } - - if( table[ j ][ 127 ] > 254 << 8 ) - table[ j ][ 127 ] = 254 << 8; - } -#endif - - // enforce constantly increasing - for (j = 0; j < 3; j++) - { - for (i = 1; i < 256; i++) - { - if (table[j][i] < table[j][i-1]) - table[j][i] = table[j][i-1]; - } - } - - if (SDL_SetWindowGammaRamp(SDL_window, table[0], table[1], table[2]) < 0) - { - ri.Printf( PRINT_DEVELOPER, "SDL_SetWindowGammaRamp() failed: %s\n", SDL_GetError() ); - } + //FIXME Ummmmm... do it with a shader maybe? What about GL1? + ri.Printf( PRINT_DEVELOPER, "Gamma adjustment not supported in SDL3\n" ); } diff --git a/code/sdl/sdl_glimp.c b/code/sdl/sdl_glimp.c index 39930261cb..e161f8d99c 100644 --- a/code/sdl/sdl_glimp.c +++ b/code/sdl/sdl_glimp.c @@ -21,9 +21,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" +# include "SDL3/SDL.h" #else -# include +# include #endif #include @@ -57,12 +57,19 @@ cvar_t *r_preferOpenGLES; int qglMajorVersion, qglMinorVersion; int qglesMajorVersion, qglesMinorVersion; -void (APIENTRYP qglActiveTextureARB) (GLenum texture); -void (APIENTRYP qglClientActiveTextureARB) (GLenum texture); -void (APIENTRYP qglMultiTexCoord2fARB) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP qglActiveTextureARB_t) (GLenum texture); +typedef void (APIENTRYP qglClientActiveTextureARB_t) (GLenum texture); +typedef void (APIENTRYP qglMultiTexCoord2fARB_t) (GLenum target, GLfloat s, GLfloat t); -void (APIENTRYP qglLockArraysEXT) (GLint first, GLsizei count); -void (APIENTRYP qglUnlockArraysEXT) (void); +typedef void (APIENTRYP qglLockArraysEXT_t) (GLint first, GLsizei count); +typedef void (APIENTRYP qglUnlockArraysEXT_t) (void); + +qglActiveTextureARB_t qglActiveTextureARB; +qglClientActiveTextureARB_t qglClientActiveTextureARB; +qglMultiTexCoord2fARB_t qglMultiTexCoord2fARB; + +qglLockArraysEXT_t qglLockArraysEXT; +qglUnlockArraysEXT_t qglUnlockArraysEXT; #define GLE(ret, name, ...) name##proc * qgl##name = NULL; QGL_1_1_PROCS; @@ -155,57 +162,63 @@ static void GLimp_DetectAvailableModes(void) SDL_Rect *modes; int numModes = 0; - SDL_DisplayMode windowMode; - int display = SDL_GetWindowDisplayIndex( SDL_window ); - if( display < 0 ) + SDL_DisplayID display = SDL_GetDisplayForWindow( SDL_window ); + if( display <= 0 ) { - ri.Printf( PRINT_WARNING, "Couldn't get window display index, no resolutions detected: %s\n", SDL_GetError() ); + ri.Printf( PRINT_WARNING, "Couldn't get display for window, no resolutions detected: %s\n", SDL_GetError() ); return; } - numSDLModes = SDL_GetNumDisplayModes( display ); - if( SDL_GetWindowDisplayMode( SDL_window, &windowMode ) < 0 || numSDLModes <= 0 ) + SDL_DisplayMode **displayModes = SDL_GetFullscreenDisplayModes( display, &numSDLModes ); + const SDL_DisplayMode *desktopMode = SDL_GetDesktopDisplayMode( display ); + + if( !desktopMode || !displayModes || numSDLModes <= 0 ) { - ri.Printf( PRINT_WARNING, "Couldn't get window display mode, no resolutions detected: %s\n", SDL_GetError() ); + SDL_free( displayModes ); + ri.Printf( PRINT_WARNING, "Couldn't get display modes, no resolutions detected: %s\n", SDL_GetError() ); return; } + SDL_DisplayMode windowMode = *desktopMode; modes = SDL_calloc( (size_t)numSDLModes, sizeof( SDL_Rect ) ); if ( !modes ) { + SDL_free( displayModes ); ri.Error( ERR_FATAL, "Out of memory" ); } + // Filter the available modes down to ones that we care about for( i = 0; i < numSDLModes; i++ ) { - SDL_DisplayMode mode; - - if( SDL_GetDisplayMode( display, i, &mode ) < 0 ) - continue; + SDL_DisplayMode *mode = displayModes[i]; - if( !mode.w || !mode.h ) + if( !mode || !mode->w || !mode->h ) { ri.Printf( PRINT_ALL, "Display supports any resolution\n" ); SDL_free( modes ); + SDL_free( displayModes ); return; } - if( windowMode.format != mode.format ) + if( windowMode.format != mode->format ) continue; // SDL can give the same resolution with different refresh rates. // Only list resolution once. for( j = 0; j < numModes; j++ ) { - if( mode.w == modes[ j ].w && mode.h == modes[ j ].h ) + if( mode->w == modes[ j ].w && mode->h == modes[ j ].h ) break; } if( j != numModes ) continue; - modes[ numModes ].w = mode.w; - modes[ numModes ].h = mode.h; + //FIXME: do we need to handle pixel density somehow? + // Not sure if/how SDL abstracts this... + + modes[ numModes ].w = mode->w; + modes[ numModes ].h = mode->h; numModes++; } @@ -228,7 +241,9 @@ static void GLimp_DetectAvailableModes(void) ri.Printf( PRINT_ALL, "Available modes: '%s'\n", buf ); ri.Cvar_Set( "r_availableModes", buf ); } + SDL_free( modes ); + SDL_free( displayModes ); } /* @@ -406,8 +421,8 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool int samples; int i = 0; SDL_Surface *icon = NULL; - Uint32 flags = SDL_WINDOW_SHOWN | SDL_WINDOW_OPENGL; - SDL_DisplayMode desktopMode; + Uint64 flags = SDL_WINDOW_OPENGL; + const SDL_DisplayMode *desktopMode = NULL; int display = 0; int x = SDL_WINDOWPOS_UNDEFINED, y = SDL_WINDOWPOS_UNDEFINED; @@ -417,24 +432,18 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool flags |= SDL_WINDOW_RESIZABLE; #ifdef USE_ICON - icon = SDL_CreateRGBSurfaceFrom( - (void *)CLIENT_WINDOW_ICON.pixel_data, + icon = SDL_CreateSurfaceFrom( CLIENT_WINDOW_ICON.width, CLIENT_WINDOW_ICON.height, - CLIENT_WINDOW_ICON.bytes_per_pixel * 8, - CLIENT_WINDOW_ICON.bytes_per_pixel * CLIENT_WINDOW_ICON.width, -#ifdef Q3_LITTLE_ENDIAN - 0x000000FF, 0x0000FF00, 0x00FF0000, 0xFF000000 -#else - 0xFF000000, 0x00FF0000, 0x0000FF00, 0x000000FF -#endif - ); + SDL_PIXELFORMAT_RGBA32, + (void *)CLIENT_WINDOW_ICON.pixel_data, + CLIENT_WINDOW_ICON.bytes_per_pixel * CLIENT_WINDOW_ICON.width); #endif // If a window exists, note its display index if( SDL_window != NULL ) { - display = SDL_GetWindowDisplayIndex( SDL_window ); + display = SDL_GetDisplayForWindow( SDL_window ); if( display < 0 ) { ri.Printf( PRINT_DEVELOPER, "SDL_GetWindowDisplayIndex() failed: %s\n", SDL_GetError() ); @@ -442,36 +451,33 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool } } - if( SDL_GetDesktopDisplayMode( display, &desktopMode ) == 0 ) + desktopMode = SDL_GetDesktopDisplayMode( display ); + if( desktopMode && desktopMode->h > 0 ) { - displayAspect = (float)desktopMode.w / (float)desktopMode.h; + displayAspect = (float)desktopMode->w / (float)desktopMode->h; ri.Printf( PRINT_ALL, "Display aspect: %.3f\n", displayAspect ); } else { - Com_Memset( &desktopMode, 0, sizeof( SDL_DisplayMode ) ); - - ri.Printf( PRINT_ALL, - "Cannot determine display aspect, assuming 1.333\n" ); + ri.Printf( PRINT_ALL, "Cannot determine display aspect, assuming 1.333\n" ); } ri.Printf (PRINT_ALL, "...setting mode %d:", mode ); - if (mode == -2) + if( mode == -2 && desktopMode ) { // use desktop video resolution - if( desktopMode.h > 0 ) + if( desktopMode->h > 0 ) { - glConfig.vidWidth = desktopMode.w; - glConfig.vidHeight = desktopMode.h; + glConfig.vidWidth = desktopMode->w; + glConfig.vidHeight = desktopMode->h; } else { glConfig.vidWidth = 640; glConfig.vidHeight = 480; - ri.Printf( PRINT_ALL, - "Cannot determine display resolution, assuming 640x480\n" ); + ri.Printf( PRINT_ALL, "Cannot determine display resolution, assuming 640x480\n" ); } glConfig.windowAspect = (float)glConfig.vidWidth / (float)glConfig.vidHeight; @@ -486,15 +492,15 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool // Center window if( r_centerWindow->integer && !fullscreen ) { - x = ( desktopMode.w / 2 ) - ( glConfig.vidWidth / 2 ); - y = ( desktopMode.h / 2 ) - ( glConfig.vidHeight / 2 ); + x = ( desktopMode->w / 2 ) - ( glConfig.vidWidth / 2 ); + y = ( desktopMode->h / 2 ) - ( glConfig.vidHeight / 2 ); } // Destroy existing state if it exists if( SDL_glContext != NULL ) { GLimp_ClearProcAddresses(); - SDL_GL_DeleteContext( SDL_glContext ); + SDL_GL_DestroyContext( SDL_glContext ); SDL_glContext = NULL; } @@ -682,19 +688,19 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 ); -#if 0 // if multisampling is enabled on X11, this causes create window to fail. - // If not allowing software GL, demand accelerated - if( !r_allowSoftwareGL->integer ) - SDL_GL_SetAttribute( SDL_GL_ACCELERATED_VISUAL, 1 ); -#endif - - if( ( SDL_window = SDL_CreateWindow( CLIENT_WINDOW_TITLE, x, y, + if( ( SDL_window = SDL_CreateWindow( CLIENT_WINDOW_TITLE, glConfig.vidWidth, glConfig.vidHeight, flags ) ) == NULL ) { ri.Printf( PRINT_DEVELOPER, "SDL_CreateWindow failed: %s\n", SDL_GetError( ) ); continue; } + // Set window position if specified + if( x != SDL_WINDOWPOS_UNDEFINED && y != SDL_WINDOWPOS_UNDEFINED ) + { + SDL_SetWindowPosition( SDL_window, x, y ); + } + if( fullscreen ) { SDL_DisplayMode desiredMode; @@ -709,11 +715,10 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool desiredMode.w = glConfig.vidWidth; desiredMode.h = glConfig.vidHeight; desiredMode.refresh_rate = glConfig.displayFrequency = ri.Cvar_VariableIntegerValue( "r_displayRefresh" ); - desiredMode.driverdata = NULL; - if( SDL_SetWindowDisplayMode( SDL_window, &desiredMode ) < 0 ) + if( !SDL_SetWindowFullscreenMode( SDL_window, &desiredMode ) ) { - ri.Printf( PRINT_DEVELOPER, "SDL_SetWindowDisplayMode failed: %s\n", SDL_GetError( ) ); + ri.Printf( PRINT_DEVELOPER, "SDL_SetWindowFullscreenMode failed: %s\n", SDL_GetError( ) ); continue; } } @@ -754,7 +759,7 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool { ri.Printf( PRINT_ALL, "GLimp_GetProcAddresses() for %s context failed\n", contextName ); GLimp_ClearProcAddresses(); - SDL_GL_DeleteContext( SDL_glContext ); + SDL_GL_DestroyContext( SDL_glContext ); SDL_glContext = NULL; continue; } @@ -769,7 +774,7 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool ri.Printf( PRINT_ALL, "GL_RENDERER is %s, rejecting %s context\n", renderer, contextName ); GLimp_ClearProcAddresses(); - SDL_GL_DeleteContext( SDL_glContext ); + SDL_GL_DestroyContext( SDL_glContext ); SDL_glContext = NULL; continue; } @@ -788,7 +793,7 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool qglClear( GL_COLOR_BUFFER_BIT ); SDL_GL_SwapWindow( SDL_window ); - if( SDL_GL_SetSwapInterval( r_swapInterval->integer ) == -1 ) + if( !SDL_GL_SetSwapInterval( r_swapInterval->integer ) ) { ri.Printf( PRINT_DEVELOPER, "SDL_GL_SetSwapInterval failed: %s\n", SDL_GetError( ) ); } @@ -806,7 +811,7 @@ static int GLimp_SetMode(int mode, qboolean fullscreen, qboolean noborder, qbool break; } - SDL_FreeSurface( icon ); + SDL_DestroySurface( icon ); if( !SDL_window ) { @@ -835,7 +840,7 @@ static qboolean GLimp_StartDriverAndSetMode(int mode, qboolean fullscreen, qbool { const char *driverName; - if (SDL_Init(SDL_INIT_VIDEO) != 0) + if (!SDL_Init(SDL_INIT_VIDEO)) { ri.Printf( PRINT_ALL, "SDL_Init( SDL_INIT_VIDEO ) FAILED (%s)\n", SDL_GetError()); return qfalse; @@ -960,9 +965,9 @@ static void GLimp_InitExtensions( qboolean fixedFunction ) { if ( r_ext_multitexture->value ) { - qglMultiTexCoord2fARB = SDL_GL_GetProcAddress( "glMultiTexCoord2fARB" ); - qglActiveTextureARB = SDL_GL_GetProcAddress( "glActiveTextureARB" ); - qglClientActiveTextureARB = SDL_GL_GetProcAddress( "glClientActiveTextureARB" ); + qglMultiTexCoord2fARB = (qglMultiTexCoord2fARB_t)SDL_GL_GetProcAddress( "glMultiTexCoord2fARB" ); + qglActiveTextureARB = (qglActiveTextureARB_t)SDL_GL_GetProcAddress( "glActiveTextureARB" ); + qglClientActiveTextureARB = (qglActiveTextureARB_t)SDL_GL_GetProcAddress( "glClientActiveTextureARB" ); if ( qglActiveTextureARB ) { @@ -998,8 +1003,8 @@ static void GLimp_InitExtensions( qboolean fixedFunction ) if ( r_ext_compiled_vertex_array->value ) { ri.Printf( PRINT_ALL, "...using GL_EXT_compiled_vertex_array\n" ); - qglLockArraysEXT = ( void ( APIENTRY * )( GLint, GLint ) ) SDL_GL_GetProcAddress( "glLockArraysEXT" ); - qglUnlockArraysEXT = ( void ( APIENTRY * )( void ) ) SDL_GL_GetProcAddress( "glUnlockArraysEXT" ); + qglLockArraysEXT = (qglLockArraysEXT_t)SDL_GL_GetProcAddress( "glLockArraysEXT" ); + qglUnlockArraysEXT = (qglUnlockArraysEXT_t)SDL_GL_GetProcAddress( "glUnlockArraysEXT" ); if (!qglLockArraysEXT || !qglUnlockArraysEXT) { ri.Error (ERR_FATAL, "bad getprocaddress"); @@ -1111,9 +1116,8 @@ void GLimp_Init( qboolean fixedFunction ) glConfig.driverType = GLDRV_ICD; glConfig.hardwareType = GLHW_GENERIC; - // Only using SDL_SetWindowBrightness to determine if hardware gamma is supported - glConfig.deviceSupportsGamma = !r_ignorehwgamma->integer && - SDL_SetWindowBrightness( SDL_window, 1.0f ) >= 0; + //FIXME SDL3 doesn't do gamma + glConfig.deviceSupportsGamma = qfalse; // get our config strings Q_strncpyz( glConfig.vendor_string, (char *) qglGetString (GL_VENDOR), sizeof( glConfig.vendor_string ) ); @@ -1199,7 +1203,7 @@ void GLimp_EndFrame( void ) if( needToToggle ) { - sdlToggled = SDL_SetWindowFullscreen( SDL_window, r_fullscreen->integer ) >= 0; + sdlToggled = SDL_SetWindowFullscreen( SDL_window, r_fullscreen->integer ); // SDL_WM_ToggleFullScreen didn't work, so do it the slow way if( !sdlToggled ) diff --git a/code/sdl/sdl_input.c b/code/sdl/sdl_input.c index dcc6bc52c1..55c6d0a7c9 100644 --- a/code/sdl/sdl_input.c +++ b/code/sdl/sdl_input.c @@ -21,9 +21,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" +# include "SDL3/SDL.h" #else -# include +# include #endif #include @@ -33,13 +33,10 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #include "../client/client.h" #include "../sys/sys_local.h" -#if !SDL_VERSION_ATLEAST(2, 0, 17) -#define KMOD_SCROLL KMOD_RESERVED -#endif static cvar_t *in_keyboardDebug = NULL; -static SDL_GameController *gamepad = NULL; +static SDL_Gamepad *gamepad = NULL; static SDL_Joystick *stick = NULL; static qboolean mouseAvailable = qfalse; @@ -66,29 +63,29 @@ static SDL_Window *SDL_window = NULL; IN_PrintKey =============== */ -static void IN_PrintKey( const SDL_Keysym *keysym, keyNum_t key, qboolean down ) +static void IN_PrintKey( const SDL_KeyboardEvent *keyEvent, keyNum_t key, qboolean down ) { if( down ) Com_Printf( "+ " ); else Com_Printf( " " ); - Com_Printf( "Scancode: 0x%02x(%s) Sym: 0x%02x(%s)", - keysym->scancode, SDL_GetScancodeName( keysym->scancode ), - keysym->sym, SDL_GetKeyName( keysym->sym ) ); - - if( keysym->mod & KMOD_LSHIFT ) Com_Printf( " KMOD_LSHIFT" ); - if( keysym->mod & KMOD_RSHIFT ) Com_Printf( " KMOD_RSHIFT" ); - if( keysym->mod & KMOD_LCTRL ) Com_Printf( " KMOD_LCTRL" ); - if( keysym->mod & KMOD_RCTRL ) Com_Printf( " KMOD_RCTRL" ); - if( keysym->mod & KMOD_LALT ) Com_Printf( " KMOD_LALT" ); - if( keysym->mod & KMOD_RALT ) Com_Printf( " KMOD_RALT" ); - if( keysym->mod & KMOD_LGUI ) Com_Printf( " KMOD_LGUI" ); - if( keysym->mod & KMOD_RGUI ) Com_Printf( " KMOD_RGUI" ); - if( keysym->mod & KMOD_NUM ) Com_Printf( " KMOD_NUM" ); - if( keysym->mod & KMOD_CAPS ) Com_Printf( " KMOD_CAPS" ); - if( keysym->mod & KMOD_MODE ) Com_Printf( " KMOD_MODE" ); - if( keysym->mod & KMOD_SCROLL ) Com_Printf( " KMOD_SCROLL" ); + Com_Printf( "Scancode: 0x%02x(%s) Key: 0x%02x(%s)", + keyEvent->scancode, SDL_GetScancodeName( keyEvent->scancode ), + keyEvent->key, SDL_GetKeyName( keyEvent->key ) ); + + if( keyEvent->mod & SDL_KMOD_LSHIFT ) Com_Printf( " SDL_KMOD_LSHIFT" ); + if( keyEvent->mod & SDL_KMOD_RSHIFT ) Com_Printf( " SDL_KMOD_RSHIFT" ); + if( keyEvent->mod & SDL_KMOD_LCTRL ) Com_Printf( " SDL_KMOD_LCTRL" ); + if( keyEvent->mod & SDL_KMOD_RCTRL ) Com_Printf( " SDL_KMOD_RCTRL" ); + if( keyEvent->mod & SDL_KMOD_LALT ) Com_Printf( " SDL_KMOD_LALT" ); + if( keyEvent->mod & SDL_KMOD_RALT ) Com_Printf( " SDL_KMOD_RALT" ); + if( keyEvent->mod & SDL_KMOD_LGUI ) Com_Printf( " SDL_KMOD_LGUI" ); + if( keyEvent->mod & SDL_KMOD_RGUI ) Com_Printf( " SDL_KMOD_RGUI" ); + if( keyEvent->mod & SDL_KMOD_NUM ) Com_Printf( " SDL_KMOD_NUM" ); + if( keyEvent->mod & SDL_KMOD_CAPS ) Com_Printf( " SDL_KMOD_CAPS" ); + if( keyEvent->mod & SDL_KMOD_MODE ) Com_Printf( " SDL_KMOD_MODE" ); + if( keyEvent->mod & SDL_KMOD_SCROLL ) Com_Printf( " SDL_KMOD_SCROLL" ); Com_Printf( " Q:0x%02x(%s)\n", key, Key_KeynumToString( key ) ); } @@ -193,29 +190,29 @@ static qboolean IN_IsConsoleKey( keyNum_t key, int character ) IN_TranslateSDLToQ3Key =============== */ -static keyNum_t IN_TranslateSDLToQ3Key( SDL_Keysym *keysym, qboolean down ) +static keyNum_t IN_TranslateSDLToQ3Key( const SDL_KeyboardEvent *keyEvent, qboolean down ) { keyNum_t key = 0; - if( keysym->scancode >= SDL_SCANCODE_1 && keysym->scancode <= SDL_SCANCODE_0 ) + if( keyEvent->scancode >= SDL_SCANCODE_1 && keyEvent->scancode <= SDL_SCANCODE_0 ) { // Always map the number keys as such even if they actually map // to other characters (eg, "1" is "&" on an AZERTY keyboard). // This is required for SDL before 2.0.6, except on Windows // which already had this behavior. - if( keysym->scancode == SDL_SCANCODE_0 ) + if( keyEvent->scancode == SDL_SCANCODE_0 ) key = '0'; else - key = '1' + keysym->scancode - SDL_SCANCODE_1; + key = '1' + keyEvent->scancode - SDL_SCANCODE_1; } - else if( keysym->sym >= SDLK_SPACE && keysym->sym < SDLK_DELETE ) + else if( keyEvent->key >= SDLK_SPACE && keyEvent->key < SDLK_DELETE ) { // These happen to match the ASCII chars - key = (int)keysym->sym; + key = (int)keyEvent->key; } else { - switch( keysym->sym ) + switch( keyEvent->key ) { case SDLK_PAGEUP: key = K_PGUP; break; case SDLK_KP_9: key = K_KP_PGUP; break; @@ -296,21 +293,21 @@ static keyNum_t IN_TranslateSDLToQ3Key( SDL_Keysym *keysym, qboolean down ) case SDLK_CAPSLOCK: key = K_CAPSLOCK; break; default: - if( !( keysym->sym & SDLK_SCANCODE_MASK ) && keysym->scancode <= 95 ) + if( !( keyEvent->key & SDLK_SCANCODE_MASK ) && keyEvent->scancode <= 95 ) { // Map Unicode characters to 95 world keys using the key's scan code. // FIXME: There aren't enough world keys to cover all the scancodes. // Maybe create a map of scancode to quake key at start up and on // key map change; allocate world key numbers as needed similar // to SDL 1.2. - key = K_WORLD_0 + (int)keysym->scancode; + key = K_WORLD_0 + (int)keyEvent->scancode; } break; } } if( in_keyboardDebug->integer ) - IN_PrintKey( keysym, key, down ); + IN_PrintKey( keyEvent, key, down ); if( IN_IsConsoleKey( key, 0 ) ) { @@ -334,7 +331,7 @@ static void IN_GobbleMotionEvents( void ) // Gobble any mouse motion events SDL_PumpEvents( ); while( ( val = SDL_PeepEvents( dummy, 1, SDL_GETEVENT, - SDL_MOUSEMOTION, SDL_MOUSEMOTION ) ) > 0 ) { } + SDL_EVENT_MOUSE_MOTION, SDL_EVENT_MOUSE_MOTION ) ) > 0 ) { } if ( val < 0 ) Com_Printf( "IN_GobbleMotionEvents failed: %s\n", SDL_GetError( ) ); @@ -352,9 +349,7 @@ static void IN_ActivateMouse( qboolean isFullscreen ) if( !mouseActive ) { - SDL_SetRelativeMouseMode( SDL_TRUE ); - SDL_SetWindowGrab( SDL_window, SDL_TRUE ); - + SDL_SetWindowRelativeMouseMode( SDL_window, true ); IN_GobbleMotionEvents( ); } @@ -363,14 +358,7 @@ static void IN_ActivateMouse( qboolean isFullscreen ) { if( in_nograb->modified || !mouseActive ) { - if( in_nograb->integer ) { - SDL_SetRelativeMouseMode( SDL_FALSE ); - SDL_SetWindowGrab( SDL_window, SDL_FALSE ); - } else { - SDL_SetRelativeMouseMode( SDL_TRUE ); - SDL_SetWindowGrab( SDL_window, SDL_TRUE ); - } - + SDL_SetWindowRelativeMouseMode( SDL_window, in_nograb->integer ? false : true ); in_nograb->modified = qfalse; } } @@ -391,7 +379,7 @@ static void IN_DeactivateMouse( qboolean isFullscreen ) // Always show the cursor when the mouse is disabled, // but not when fullscreen if( !isFullscreen ) - SDL_ShowCursor( SDL_TRUE ); + SDL_ShowCursor(); if( !mouseAvailable ) return; @@ -399,9 +387,7 @@ static void IN_DeactivateMouse( qboolean isFullscreen ) if( mouseActive ) { IN_GobbleMotionEvents( ); - - SDL_SetWindowGrab( SDL_window, SDL_FALSE ); - SDL_SetRelativeMouseMode( SDL_FALSE ); + SDL_SetWindowRelativeMouseMode( SDL_window, false ); // Don't warp the mouse unless the cursor is within the window if( SDL_GetWindowFlags( SDL_window ) & SDL_WINDOW_MOUSE_FOCUS ) @@ -439,7 +425,7 @@ static int hat_keys[16] = { struct { - qboolean buttons[SDL_CONTROLLER_BUTTON_MAX + 1]; // +1 because old max was 16, current SDL_CONTROLLER_BUTTON_MAX is 15 + qboolean buttons[SDL_GAMEPAD_BUTTON_COUNT]; unsigned int oldaxes; int oldaaxes[MAX_JOYSTICK_AXIS]; unsigned int oldhats; @@ -456,36 +442,23 @@ static void IN_InitJoystick( void ) int i = 0; int total = 0; char buf[16384] = ""; + SDL_JoystickID *joysticks = NULL; + const char *joystickName = NULL; if (gamepad) - SDL_GameControllerClose(gamepad); + SDL_CloseGamepad(gamepad); if (stick != NULL) - SDL_JoystickClose(stick); + SDL_CloseJoystick(stick); stick = NULL; gamepad = NULL; memset(&stick_state, '\0', sizeof (stick_state)); - // SDL 2.0.4 requires SDL_INIT_JOYSTICK to be initialized separately from - // SDL_INIT_GAMECONTROLLER for SDL_JoystickOpen() to work correctly, - // despite https://wiki.libsdl.org/SDL_Init (retrieved 2016-08-16) - // indicating SDL_INIT_JOYSTICK should be initialized automatically. - if (!SDL_WasInit(SDL_INIT_JOYSTICK)) - { - Com_DPrintf("Calling SDL_Init(SDL_INIT_JOYSTICK)...\n"); - if (SDL_Init(SDL_INIT_JOYSTICK) != 0) - { - Com_DPrintf("SDL_Init(SDL_INIT_JOYSTICK) failed: %s\n", SDL_GetError()); - return; - } - Com_DPrintf("SDL_Init(SDL_INIT_JOYSTICK) passed.\n"); - } - - if (!SDL_WasInit(SDL_INIT_GAMECONTROLLER)) + if (!SDL_WasInit(SDL_INIT_GAMEPAD)) { Com_DPrintf("Calling SDL_Init(SDL_INIT_GAMECONTROLLER)...\n"); - if (SDL_Init(SDL_INIT_GAMECONTROLLER) != 0) + if (!SDL_Init(SDL_INIT_GAMEPAD)) { Com_DPrintf("SDL_Init(SDL_INIT_GAMECONTROLLER) failed: %s\n", SDL_GetError()); return; @@ -493,16 +466,20 @@ static void IN_InitJoystick( void ) Com_DPrintf("SDL_Init(SDL_INIT_GAMECONTROLLER) passed.\n"); } - total = SDL_NumJoysticks(); + joysticks = SDL_GetJoysticks(&total); Com_DPrintf("%d possible joysticks\n", total); // Print list and build cvar to allow ui to select joystick. - for (i = 0; i < total; i++) + while (joysticks[i] != 0) { - Q_strcat(buf, sizeof(buf), SDL_JoystickNameForIndex(i)); + const char *name = SDL_GetJoystickNameForID(joysticks[i]); + Q_strcat(buf, sizeof(buf), name ? name : "Unknown"); Q_strcat(buf, sizeof(buf), "\n"); + i++; } + SDL_free(joysticks); + Cvar_Get( "in_availableJoysticks", "", CVAR_ROM ); // Update cvar on in_restart or controller add/remove. @@ -510,7 +487,7 @@ static void IN_InitJoystick( void ) if( !in_joystick->integer ) { Com_DPrintf( "Joystick is not active.\n" ); - SDL_QuitSubSystem(SDL_INIT_GAMECONTROLLER); + SDL_QuitSubSystem(SDL_INIT_GAMEPAD); return; } @@ -520,27 +497,28 @@ static void IN_InitJoystick( void ) in_joystickUseAnalog = Cvar_Get( "in_joystickUseAnalog", "0", CVAR_ARCHIVE ); - stick = SDL_JoystickOpen( in_joystickNo->integer ); + stick = SDL_OpenJoystick( in_joystickNo->integer ); if (stick == NULL) { Com_DPrintf( "No joystick opened: %s\n", SDL_GetError() ); return; } - if (SDL_IsGameController(in_joystickNo->integer)) - gamepad = SDL_GameControllerOpen(in_joystickNo->integer); + if (SDL_IsGamepad(in_joystickNo->integer)) + gamepad = SDL_OpenGamepad(in_joystickNo->integer); + joystickName = SDL_GetJoystickNameForID(in_joystickNo->integer); Com_DPrintf( "Joystick %d opened\n", in_joystickNo->integer ); - Com_DPrintf( "Name: %s\n", SDL_JoystickNameForIndex(in_joystickNo->integer) ); - Com_DPrintf( "Axes: %d\n", SDL_JoystickNumAxes(stick) ); - Com_DPrintf( "Hats: %d\n", SDL_JoystickNumHats(stick) ); - Com_DPrintf( "Buttons: %d\n", SDL_JoystickNumButtons(stick) ); - Com_DPrintf( "Balls: %d\n", SDL_JoystickNumBalls(stick) ); + Com_DPrintf( "Name: %s\n", joystickName ? joystickName : "Unknown" ); + Com_DPrintf( "Axes: %d\n", SDL_GetNumJoystickAxes(stick) ); + Com_DPrintf( "Hats: %d\n", SDL_GetNumJoystickHats(stick) ); + Com_DPrintf( "Buttons: %d\n", SDL_GetNumJoystickButtons(stick) ); + Com_DPrintf( "Balls: %d\n", SDL_GetNumJoystickBalls(stick) ); Com_DPrintf( "Use Analog: %s\n", in_joystickUseAnalog->integer ? "Yes" : "No" ); Com_DPrintf( "Is gamepad: %s\n", gamepad ? "Yes" : "No" ); - SDL_JoystickEventState(SDL_QUERY); - SDL_GameControllerEventState(SDL_QUERY); + SDL_SetJoystickEventsEnabled(true); + SDL_SetGamepadEventsEnabled(true); } /* @@ -550,7 +528,7 @@ IN_ShutdownJoystick */ static void IN_ShutdownJoystick( void ) { - if ( !SDL_WasInit( SDL_INIT_GAMECONTROLLER ) ) + if ( !SDL_WasInit( SDL_INIT_GAMEPAD ) ) return; if ( !SDL_WasInit( SDL_INIT_JOYSTICK ) ) @@ -558,17 +536,17 @@ static void IN_ShutdownJoystick( void ) if (gamepad) { - SDL_GameControllerClose(gamepad); + SDL_CloseGamepad(gamepad); gamepad = NULL; } if (stick) { - SDL_JoystickClose(stick); + SDL_CloseJoystick(stick); stick = NULL; } - SDL_QuitSubSystem(SDL_INIT_GAMECONTROLLER); + SDL_QuitSubSystem(SDL_INIT_GAMEPAD); SDL_QuitSubSystem(SDL_INIT_JOYSTICK); } @@ -646,33 +624,36 @@ static qboolean KeyToAxisAndSign(int keynum, int *outAxis, int *outSign) IN_KeyFor =============== */ -static keyNum_t IN_KeyFor( SDL_GameControllerButton sdlButton ) +static keyNum_t IN_KeyFor( SDL_GamepadButton sdlButton ) { switch(sdlButton) { - case SDL_CONTROLLER_BUTTON_A: return K_PAD0_A; - case SDL_CONTROLLER_BUTTON_B: return K_PAD0_B; - case SDL_CONTROLLER_BUTTON_X: return K_PAD0_X; - case SDL_CONTROLLER_BUTTON_Y: return K_PAD0_Y; - case SDL_CONTROLLER_BUTTON_BACK: return K_PAD0_BACK; - case SDL_CONTROLLER_BUTTON_GUIDE: return K_PAD0_GUIDE; - case SDL_CONTROLLER_BUTTON_START: return K_PAD0_START; - case SDL_CONTROLLER_BUTTON_LEFTSTICK: return K_PAD0_LEFTSTICK_CLICK; - case SDL_CONTROLLER_BUTTON_RIGHTSTICK: return K_PAD0_RIGHTSTICK_CLICK; - case SDL_CONTROLLER_BUTTON_LEFTSHOULDER: return K_PAD0_LEFTSHOULDER; - case SDL_CONTROLLER_BUTTON_RIGHTSHOULDER: return K_PAD0_RIGHTSHOULDER; - case SDL_CONTROLLER_BUTTON_DPAD_UP: return K_PAD0_DPAD_UP; - case SDL_CONTROLLER_BUTTON_DPAD_DOWN: return K_PAD0_DPAD_DOWN; - case SDL_CONTROLLER_BUTTON_DPAD_LEFT: return K_PAD0_DPAD_LEFT; - case SDL_CONTROLLER_BUTTON_DPAD_RIGHT: return K_PAD0_DPAD_RIGHT; -#if SDL_VERSION_ATLEAST( 2, 0, 14 ) - case SDL_CONTROLLER_BUTTON_MISC1: return K_PAD0_MISC1; - case SDL_CONTROLLER_BUTTON_PADDLE1: return K_PAD0_PADDLE1; - case SDL_CONTROLLER_BUTTON_PADDLE2: return K_PAD0_PADDLE2; - case SDL_CONTROLLER_BUTTON_PADDLE3: return K_PAD0_PADDLE3; - case SDL_CONTROLLER_BUTTON_PADDLE4: return K_PAD0_PADDLE4; - case SDL_CONTROLLER_BUTTON_TOUCHPAD: return K_PAD0_TOUCHPAD; -#endif + case SDL_GAMEPAD_BUTTON_SOUTH: return K_PAD0_A; + case SDL_GAMEPAD_BUTTON_EAST: return K_PAD0_B; + case SDL_GAMEPAD_BUTTON_WEST: return K_PAD0_X; + case SDL_GAMEPAD_BUTTON_NORTH: return K_PAD0_Y; + case SDL_GAMEPAD_BUTTON_BACK: return K_PAD0_BACK; + case SDL_GAMEPAD_BUTTON_GUIDE: return K_PAD0_GUIDE; + case SDL_GAMEPAD_BUTTON_START: return K_PAD0_START; + case SDL_GAMEPAD_BUTTON_LEFT_STICK: return K_PAD0_LEFTSTICK_CLICK; + case SDL_GAMEPAD_BUTTON_RIGHT_STICK: return K_PAD0_RIGHTSTICK_CLICK; + case SDL_GAMEPAD_BUTTON_LEFT_SHOULDER: return K_PAD0_LEFTSHOULDER; + case SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER: return K_PAD0_RIGHTSHOULDER; + case SDL_GAMEPAD_BUTTON_DPAD_UP: return K_PAD0_DPAD_UP; + case SDL_GAMEPAD_BUTTON_DPAD_DOWN: return K_PAD0_DPAD_DOWN; + case SDL_GAMEPAD_BUTTON_DPAD_LEFT: return K_PAD0_DPAD_LEFT; + case SDL_GAMEPAD_BUTTON_DPAD_RIGHT: return K_PAD0_DPAD_RIGHT; + case SDL_GAMEPAD_BUTTON_MISC1: return K_PAD0_MISC1; + case SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1: return K_PAD0_PADDLE1; + case SDL_GAMEPAD_BUTTON_LEFT_PADDLE1: return K_PAD0_PADDLE2; + case SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2: return K_PAD0_PADDLE3; + case SDL_GAMEPAD_BUTTON_LEFT_PADDLE2: return K_PAD0_PADDLE4; + case SDL_GAMEPAD_BUTTON_TOUCHPAD: return K_PAD0_TOUCHPAD; + case SDL_GAMEPAD_BUTTON_MISC2: return K_PAD0_MISC2; + case SDL_GAMEPAD_BUTTON_MISC3: return K_PAD0_MISC3; + case SDL_GAMEPAD_BUTTON_MISC4: return K_PAD0_MISC4; + case SDL_GAMEPAD_BUTTON_MISC5: return K_PAD0_MISC5; + case SDL_GAMEPAD_BUTTON_MISC6: return K_PAD0_MISC6; default: Com_Error(ERR_DROP, "IN_KeyFor: unhandled SDL button: %d", sdlButton); @@ -693,13 +674,13 @@ static void IN_GamepadMove( void ) int translatedAxes[MAX_JOYSTICK_AXIS]; qboolean translatedAxesSet[MAX_JOYSTICK_AXIS]; - SDL_GameControllerUpdate(); + SDL_UpdateGamepads(); // check buttons - for (i = 0; i < SDL_CONTROLLER_BUTTON_MAX; i++) + for (i = 0; i < SDL_GAMEPAD_BUTTON_COUNT; i++) { - SDL_GameControllerButton sdlButton = SDL_CONTROLLER_BUTTON_A + i; - qboolean pressed = SDL_GameControllerGetButton(gamepad, sdlButton); + SDL_GamepadButton sdlButton = SDL_GAMEPAD_BUTTON_SOUTH + i; + qboolean pressed = SDL_GetGamepadButton(gamepad, sdlButton); if (pressed != stick_state.buttons[i]) { Com_QueueEvent(in_eventTime, SE_KEY, IN_KeyFor(sdlButton), pressed, 0, NULL); @@ -719,9 +700,9 @@ static void IN_GamepadMove( void ) } // check axes - for (i = 0; i < SDL_CONTROLLER_AXIS_MAX; i++) + for (i = 0; i < SDL_GAMEPAD_AXIS_COUNT; i++) { - int axis = SDL_GameControllerGetAxis(gamepad, SDL_CONTROLLER_AXIS_LEFTX + i); + int axis = SDL_GetGamepadAxis(gamepad, SDL_GAMEPAD_AXIS_LEFTX + i); int oldAxis = stick_state.oldaaxes[i]; // Smoothly ramp from dead zone to maximum value @@ -734,8 +715,8 @@ static void IN_GamepadMove( void ) if (axis != oldAxis) { - const int negMap[SDL_CONTROLLER_AXIS_MAX] = { K_PAD0_LEFTSTICK_LEFT, K_PAD0_LEFTSTICK_UP, K_PAD0_RIGHTSTICK_LEFT, K_PAD0_RIGHTSTICK_UP, 0, 0 }; - const int posMap[SDL_CONTROLLER_AXIS_MAX] = { K_PAD0_LEFTSTICK_RIGHT, K_PAD0_LEFTSTICK_DOWN, K_PAD0_RIGHTSTICK_RIGHT, K_PAD0_RIGHTSTICK_DOWN, K_PAD0_LEFTTRIGGER, K_PAD0_RIGHTTRIGGER }; + const int negMap[SDL_GAMEPAD_AXIS_COUNT] = { K_PAD0_LEFTSTICK_LEFT, K_PAD0_LEFTSTICK_UP, K_PAD0_RIGHTSTICK_LEFT, K_PAD0_RIGHTSTICK_UP, 0, 0 }; + const int posMap[SDL_GAMEPAD_AXIS_COUNT] = { K_PAD0_LEFTSTICK_RIGHT, K_PAD0_LEFTSTICK_DOWN, K_PAD0_RIGHTSTICK_RIGHT, K_PAD0_RIGHTSTICK_DOWN, K_PAD0_LEFTTRIGGER, K_PAD0_RIGHTTRIGGER }; qboolean posAnalog = qfalse, negAnalog = qfalse; int negKey = negMap[i]; @@ -833,10 +814,10 @@ static void IN_JoyMove( void ) if (!stick) return; - SDL_JoystickUpdate(); + SDL_UpdateJoysticks(); // update the ball state. - total = SDL_JoystickNumBalls(stick); + total = SDL_GetNumJoystickBalls(stick); if (total > 0) { int balldx = 0; @@ -845,7 +826,7 @@ static void IN_JoyMove( void ) { int dx = 0; int dy = 0; - SDL_JoystickGetBall(stick, i, &dx, &dy); + SDL_GetJoystickBall(stick, i, &dx, &dy); balldx += dx; balldy += dy; } @@ -862,14 +843,14 @@ static void IN_JoyMove( void ) } // now query the stick buttons... - total = SDL_JoystickNumButtons(stick); + total = SDL_GetNumJoystickButtons(stick); if (total > 0) { if (total > ARRAY_LEN(stick_state.buttons)) total = ARRAY_LEN(stick_state.buttons); for (i = 0; i < total; i++) { - qboolean pressed = (SDL_JoystickGetButton(stick, i) != 0); + qboolean pressed = SDL_GetJoystickButton(stick, i); if (pressed != stick_state.buttons[i]) { Com_QueueEvent( in_eventTime, SE_KEY, K_JOY1 + i, pressed, 0, NULL ); @@ -879,13 +860,13 @@ static void IN_JoyMove( void ) } // look at the hats... - total = SDL_JoystickNumHats(stick); + total = SDL_GetNumJoystickHats(stick); if (total > 0) { if (total > 4) total = 4; for (i = 0; i < total; i++) { - ((Uint8 *)&hats)[i] = SDL_JoystickGetHat(stick, i); + ((Uint8 *)&hats)[i] = SDL_GetJoystickHat(stick, i); } } @@ -968,7 +949,7 @@ static void IN_JoyMove( void ) stick_state.oldhats = hats; // finally, look at the axes... - total = SDL_JoystickNumAxes(stick); + total = SDL_GetNumJoystickAxes(stick); if (total > 0) { if (in_joystickUseAnalog->integer) @@ -976,7 +957,7 @@ static void IN_JoyMove( void ) if (total > MAX_JOYSTICK_AXIS) total = MAX_JOYSTICK_AXIS; for (i = 0; i < total; i++) { - Sint16 axis = SDL_JoystickGetAxis(stick, i); + Sint16 axis = SDL_GetJoystickAxis(stick, i); float f = ( (float) abs(axis) ) / 32767.0f; if( f < in_joystickThreshold->value ) axis = 0; @@ -993,7 +974,7 @@ static void IN_JoyMove( void ) if (total > 16) total = 16; for (i = 0; i < total; i++) { - Sint16 axis = SDL_JoystickGetAxis(stick, i); + Sint16 axis = SDL_GetJoystickAxis(stick, i); float f = ( (float) axis ) / 32767.0f; if( f < -in_joystickThreshold->value ) { axes |= ( 1 << ( i * 2 ) ); @@ -1040,11 +1021,11 @@ static void IN_ProcessEvents( void ) { switch( e.type ) { - case SDL_KEYDOWN: + case SDL_EVENT_KEY_DOWN: if ( e.key.repeat && Key_GetCatcher( ) == 0 ) break; - if( ( key = IN_TranslateSDLToQ3Key( &e.key.keysym, qtrue ) ) ) + if( ( key = IN_TranslateSDLToQ3Key( &e.key, qtrue ) ) ) Com_QueueEvent( in_eventTime, SE_KEY, key, qtrue, 0, NULL ); if( key == K_BACKSPACE ) @@ -1055,17 +1036,17 @@ static void IN_ProcessEvents( void ) lastKeyDown = key; break; - case SDL_KEYUP: - if( ( key = IN_TranslateSDLToQ3Key( &e.key.keysym, qfalse ) ) ) + case SDL_EVENT_KEY_UP: + if( ( key = IN_TranslateSDLToQ3Key( &e.key, qfalse ) ) ) Com_QueueEvent( in_eventTime, SE_KEY, key, qfalse, 0, NULL ); lastKeyDown = 0; break; - case SDL_TEXTINPUT: + case SDL_EVENT_TEXT_INPUT: if( lastKeyDown != K_CONSOLE ) { - char *c = e.text.text; + const char *c = e.text.text; // Quick and dirty UTF-8 to UTF-32 conversion while( *c ) @@ -1112,7 +1093,7 @@ static void IN_ProcessEvents( void ) } break; - case SDL_MOUSEMOTION: + case SDL_EVENT_MOUSE_MOTION: if( mouseActive ) { if( !e.motion.xrel && !e.motion.yrel ) @@ -1121,8 +1102,8 @@ static void IN_ProcessEvents( void ) } break; - case SDL_MOUSEBUTTONDOWN: - case SDL_MOUSEBUTTONUP: + case SDL_EVENT_MOUSE_BUTTON_DOWN: + case SDL_EVENT_MOUSE_BUTTON_UP: { int b; switch( e.button.button ) @@ -1135,11 +1116,11 @@ static void IN_ProcessEvents( void ) default: b = K_AUX1 + ( e.button.button - SDL_BUTTON_X2 + 1 ) % 16; break; } Com_QueueEvent( in_eventTime, SE_KEY, b, - ( e.type == SDL_MOUSEBUTTONDOWN ? qtrue : qfalse ), 0, NULL ); + ( e.type == SDL_EVENT_MOUSE_BUTTON_DOWN ? qtrue : qfalse ), 0, NULL ); } break; - case SDL_MOUSEWHEEL: + case SDL_EVENT_MOUSE_WHEEL: if( e.wheel.y > 0 ) { Com_QueueEvent( in_eventTime, SE_KEY, K_MWHEELUP, qtrue, 0, NULL ); @@ -1152,61 +1133,56 @@ static void IN_ProcessEvents( void ) } break; - case SDL_CONTROLLERDEVICEADDED: - case SDL_CONTROLLERDEVICEREMOVED: + case SDL_EVENT_GAMEPAD_ADDED: + case SDL_EVENT_GAMEPAD_REMOVED: if (in_joystick->integer) IN_InitJoystick(); break; - case SDL_QUIT: + case SDL_EVENT_QUIT: Cbuf_ExecuteText(EXEC_NOW, "quit Closed window\n"); break; - case SDL_WINDOWEVENT: - switch( e.window.event ) + case SDL_EVENT_WINDOW_RESIZED: { - case SDL_WINDOWEVENT_RESIZED: - { - int width, height; + int width, height; - width = e.window.data1; - height = e.window.data2; + width = e.window.data1; + height = e.window.data2; - // ignore this event on fullscreen - if( cls.glconfig.isFullscreen ) - { - break; - } - - // check if size actually changed - if( cls.glconfig.vidWidth == width && cls.glconfig.vidHeight == height ) - { - break; - } - - Cvar_SetValue( "r_customwidth", width ); - Cvar_SetValue( "r_customheight", height ); - Cvar_Set( "r_mode", "-1" ); + // ignore this event on fullscreen + if( cls.glconfig.isFullscreen ) + { + break; + } - // Wait until user stops dragging for 1 second, so - // we aren't constantly recreating the GL context while - // he tries to drag... - vidRestartTime = Sys_Milliseconds( ) + 1000; - } + // check if size actually changed + if( cls.glconfig.vidWidth == width && cls.glconfig.vidHeight == height ) + { break; + } - case SDL_WINDOWEVENT_MINIMIZED: Cvar_SetValue( "com_minimized", 1 ); break; - case SDL_WINDOWEVENT_RESTORED: - case SDL_WINDOWEVENT_MAXIMIZED: Cvar_SetValue( "com_minimized", 0 ); break; - case SDL_WINDOWEVENT_FOCUS_LOST: Cvar_SetValue( "com_unfocused", 1 ); break; - case SDL_WINDOWEVENT_FOCUS_GAINED: Cvar_SetValue( "com_unfocused", 0 ); break; + Cvar_SetValue( "r_customwidth", width ); + Cvar_SetValue( "r_customheight", height ); + Cvar_Set( "r_mode", "-1" ); + + // Wait until user stops dragging for 1 second, so + // we aren't constantly recreating the GL context while + // they try to drag... + vidRestartTime = Sys_Milliseconds( ) + 1000; } break; + case SDL_EVENT_WINDOW_MINIMIZED: Cvar_SetValue( "com_minimized", 1 ); break; + case SDL_EVENT_WINDOW_RESTORED: + case SDL_EVENT_WINDOW_MAXIMIZED: Cvar_SetValue( "com_minimized", 0 ); break; + case SDL_EVENT_WINDOW_FOCUS_LOST: Cvar_SetValue( "com_unfocused", 1 ); break; + case SDL_EVENT_WINDOW_FOCUS_GAINED: Cvar_SetValue( "com_unfocused", 0 ); break; + #if defined(PROTOCOL_HANDLER) && defined(__APPLE__) - case SDL_DROPFILE: + case SDL_EVENT_DROP_FILE: { - char *filename = e.drop.file; + const char *filename = e.drop.data; // Handle macOS open URL event. URL protocol scheme must be set in Info.plist. if( !Q_strncmp( filename, PROTOCOL_HANDLER ":", strlen( PROTOCOL_HANDLER ":" ) ) ) @@ -1219,8 +1195,6 @@ static void IN_ProcessEvents( void ) free( protocolCommand ); } } - - SDL_free( filename ); } break; #endif @@ -1308,10 +1282,10 @@ void IN_Init( void *windowData ) in_joystickThreshold = Cvar_Get( "joy_threshold", "0.15", CVAR_ARCHIVE ); #if defined(PROTOCOL_HANDLER) && defined(__APPLE__) - SDL_EventState( SDL_DROPFILE, SDL_ENABLE ); + SDL_SetEventEnabled( SDL_EVENT_DROP_FILE, true ); #endif - SDL_StartTextInput( ); + SDL_StartTextInput( SDL_window ); mouseAvailable = ( in_mouse->value != 0 ); IN_DeactivateMouse( Cvar_VariableIntegerValue( "r_fullscreen" ) != 0 ); @@ -1331,7 +1305,7 @@ IN_Shutdown */ void IN_Shutdown( void ) { - SDL_StopTextInput( ); + SDL_StopTextInput( SDL_window ); IN_DeactivateMouse( Cvar_VariableIntegerValue( "r_fullscreen" ) != 0 ); mouseAvailable = qfalse; diff --git a/code/sdl/sdl_snd.c b/code/sdl/sdl_snd.c index e8d04a38f4..9f2f069022 100644 --- a/code/sdl/sdl_snd.c +++ b/code/sdl/sdl_snd.c @@ -24,9 +24,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #include #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" +# include "SDL3/SDL.h" #else -# include +# include #endif #include "../qcommon/q_shared.h" @@ -46,13 +46,14 @@ static int dmapos = 0; static int dmasize = 0; static SDL_AudioDeviceID sdlPlaybackDevice; +static SDL_AudioStream *sdlPlaybackStream; -#if defined USE_VOIP && SDL_VERSION_ATLEAST( 2, 0, 5 ) +#ifdef USE_VOIP #define USE_SDL_AUDIO_CAPTURE static SDL_AudioDeviceID sdlCaptureDevice; +static SDL_AudioStream *sdlCaptureStream; static cvar_t *s_sdlCapture; -static float sdlMasterGain = 1.0f; #endif @@ -61,74 +62,36 @@ static float sdlMasterGain = 1.0f; SNDDMA_AudioCallback =============== */ -static void SNDDMA_AudioCallback(void *userdata, Uint8 *stream, int len) +static void SDLCALL SNDDMA_AudioCallback(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount) { + if (!snd_inited || additional_amount <= 0) { + return; + } + int pos = (dmapos * (dma.samplebits/8)); if (pos >= dmasize) dmapos = pos = 0; - if (!snd_inited) /* shouldn't happen, but just in case... */ + int tobufend = dmasize - pos; /* bytes to buffer's end. */ + int len1 = additional_amount; + int len2 = 0; + + if (len1 > tobufend) { - memset(stream, '\0', len); - return; + len1 = tobufend; + len2 = additional_amount - len1; } - else + SDL_PutAudioStreamData(stream, dma.buffer + pos, len1); + if (len2 <= 0) + dmapos += (len1 / (dma.samplebits/8)); + else /* wraparound? */ { - int tobufend = dmasize - pos; /* bytes to buffer's end. */ - int len1 = len; - int len2 = 0; - - if (len1 > tobufend) - { - len1 = tobufend; - len2 = len - len1; - } - memcpy(stream, dma.buffer + pos, len1); - if (len2 <= 0) - dmapos += (len1 / (dma.samplebits/8)); - else /* wraparound? */ - { - memcpy(stream+len1, dma.buffer, len2); - dmapos = (len2 / (dma.samplebits/8)); - } + SDL_PutAudioStreamData(stream, dma.buffer, len2); + dmapos = (len2 / (dma.samplebits/8)); } if (dmapos >= dmasize) dmapos = 0; - -#ifdef USE_SDL_AUDIO_CAPTURE - if (sdlMasterGain != 1.0f) - { - int i; - if (dma.isfloat && (dma.samplebits == 32)) - { - float *ptr = (float *) stream; - len /= sizeof (*ptr); - for (i = 0; i < len; i++, ptr++) - { - *ptr *= sdlMasterGain; - } - } - else if (dma.samplebits == 16) - { - Sint16 *ptr = (Sint16 *) stream; - len /= sizeof (*ptr); - for (i = 0; i < len; i++, ptr++) - { - *ptr = (Sint16) (((float) *ptr) * sdlMasterGain); - } - } - else if (dma.samplebits == 8) - { - Uint8 *ptr = (Uint8 *) stream; - len /= sizeof (*ptr); - for (i = 0; i < len; i++, ptr++) - { - *ptr = (Uint8) (((float) *ptr) * sdlMasterGain); - } - } - } -#endif } static struct @@ -137,14 +100,12 @@ static struct char *stringFormat; } formatToStringTable[ ] = { - { AUDIO_U8, "AUDIO_U8" }, - { AUDIO_S8, "AUDIO_S8" }, - { AUDIO_U16LSB, "AUDIO_U16LSB" }, - { AUDIO_S16LSB, "AUDIO_S16LSB" }, - { AUDIO_U16MSB, "AUDIO_U16MSB" }, - { AUDIO_S16MSB, "AUDIO_S16MSB" }, - { AUDIO_F32LSB, "AUDIO_F32LSB" }, - { AUDIO_F32MSB, "AUDIO_F32MSB" } + { SDL_AUDIO_U8, "SDL_AUDIO_U8" }, + { SDL_AUDIO_S8, "SDL_AUDIO_S8" }, + { SDL_AUDIO_S16LE, "SDL_AUDIO_S16LE" }, + { SDL_AUDIO_S16BE, "SDL_AUDIO_S16BE" }, + { SDL_AUDIO_F32LE, "SDL_AUDIO_F32LE" }, + { SDL_AUDIO_F32BE, "SDL_AUDIO_F32BE" } }; static int formatToStringTableSize = ARRAY_LEN( formatToStringTable ); @@ -174,7 +135,6 @@ static void SNDDMA_PrintAudiospec(const char *str, const SDL_AudioSpec *spec) } Com_Printf( " Freq: %d\n", (int) spec->freq ); - Com_Printf( " Samples: %d\n", (int) spec->samples ); Com_Printf( " Channels: %d\n", (int) spec->channels ); } @@ -187,6 +147,7 @@ qboolean SNDDMA_Init(void) { SDL_AudioSpec desired; SDL_AudioSpec obtained; + int sample_frames = 0; int tmp; if (snd_inited) @@ -202,7 +163,7 @@ qboolean SNDDMA_Init(void) Com_Printf( "SDL_Init( SDL_INIT_AUDIO )... " ); - if (SDL_Init(SDL_INIT_AUDIO) != 0) + if (!SDL_Init(SDL_INIT_AUDIO)) { Com_Printf( "FAILED (%s)\n", SDL_GetError( ) ); return qfalse; @@ -220,37 +181,27 @@ qboolean SNDDMA_Init(void) tmp = 16; desired.freq = (int) s_sdlSpeed->value; - if(!desired.freq) desired.freq = 22050; - desired.format = ((tmp == 16) ? AUDIO_S16SYS : AUDIO_U8); - - // I dunno if this is the best idea, but I'll give it a try... - // should probably check a cvar for this... - if (s_sdlDevSamps->value) - desired.samples = s_sdlDevSamps->value; - else - { - // just pick a sane default. - if (desired.freq <= 11025) - desired.samples = 256; - else if (desired.freq <= 22050) - desired.samples = 512; - else if (desired.freq <= 44100) - desired.samples = 1024; - else - desired.samples = 2048; // (*shrug*) - } - + if(!desired.freq) desired.freq = 44100; + desired.format = ((tmp == 16) ? SDL_AUDIO_S16 : SDL_AUDIO_U8); desired.channels = (int) s_sdlChannels->value; - desired.callback = SNDDMA_AudioCallback; - sdlPlaybackDevice = SDL_OpenAudioDevice(NULL, SDL_FALSE, &desired, &obtained, SDL_AUDIO_ALLOW_ANY_CHANGE); - if (sdlPlaybackDevice == 0) + sdlPlaybackStream = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &desired, SNDDMA_AudioCallback, NULL); + if (sdlPlaybackStream == NULL) { - Com_Printf("SDL_OpenAudioDevice() failed: %s\n", SDL_GetError()); + Com_Printf("SDL_OpenAudioDeviceStream() failed: %s\n", SDL_GetError()); SDL_QuitSubSystem(SDL_INIT_AUDIO); return qfalse; } + sdlPlaybackDevice = SDL_GetAudioStreamDevice(sdlPlaybackStream); + if (!SDL_GetAudioDeviceFormat(sdlPlaybackDevice, &obtained, &sample_frames)) + { + Com_Printf("SDL_GetAudioDeviceFormat() failed: %s\n", SDL_GetError()); + // Use desired format if we can't get the actual format + obtained = desired; + sample_frames = 1024; + } + SNDDMA_PrintAudiospec("SDL_AudioSpec", &obtained); // dma.samples needs to be big, or id's mixer will just refuse to @@ -262,7 +213,7 @@ qboolean SNDDMA_Init(void) // reasonable...this is why I let the user override. tmp = s_sdlMixSamps->value; if (!tmp) - tmp = (obtained.samples * obtained.channels) * 10; + tmp = (sample_frames * obtained.channels) * 10; // samples must be divisible by number of channels tmp -= tmp % obtained.channels; @@ -297,19 +248,21 @@ qboolean SNDDMA_Init(void) SDL_AudioSpec spec; SDL_zero(spec); spec.freq = 48000; - spec.format = AUDIO_S16SYS; + spec.format = SDL_AUDIO_S16; spec.channels = 1; - spec.samples = VOIP_MAX_PACKET_SAMPLES * 4; - sdlCaptureDevice = SDL_OpenAudioDevice(NULL, SDL_TRUE, &spec, NULL, 0); + sdlCaptureStream = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_RECORDING, &spec, NULL, NULL); + if (sdlCaptureStream != NULL) { + sdlCaptureDevice = SDL_GetAudioStreamDevice(sdlCaptureStream); + } else { + sdlCaptureDevice = 0; + } Com_Printf( "SDL capture device %s.\n", (sdlCaptureDevice == 0) ? "failed to open" : "opened"); } - - sdlMasterGain = 1.0f; #endif - Com_Printf("Starting SDL audio callback...\n"); - SDL_PauseAudioDevice(sdlPlaybackDevice, 0); // start callback. + Com_Printf("Starting SDL audio stream...\n"); + SDL_ResumeAudioDevice(sdlPlaybackDevice); // don't unpause the capture device; we'll do that in StartCapture. Com_Printf("SDL audio initialized.\n"); @@ -334,20 +287,22 @@ SNDDMA_Shutdown */ void SNDDMA_Shutdown(void) { - if (sdlPlaybackDevice != 0) + if (sdlPlaybackStream != NULL) { - Com_Printf("Closing SDL audio playback device...\n"); - SDL_CloseAudioDevice(sdlPlaybackDevice); - Com_Printf("SDL audio playback device closed.\n"); + Com_Printf("Closing SDL audio playback stream...\n"); + SDL_DestroyAudioStream(sdlPlaybackStream); + Com_Printf("SDL audio playback stream closed.\n"); + sdlPlaybackStream = NULL; sdlPlaybackDevice = 0; } #ifdef USE_SDL_AUDIO_CAPTURE - if (sdlCaptureDevice) + if (sdlCaptureStream != NULL) { - Com_Printf("Closing SDL audio capture device...\n"); - SDL_CloseAudioDevice(sdlCaptureDevice); - Com_Printf("SDL audio capture device closed.\n"); + Com_Printf("Closing SDL audio capture stream...\n"); + SDL_DestroyAudioStream(sdlCaptureStream); + Com_Printf("SDL audio capture stream closed.\n"); + sdlCaptureStream = NULL; sdlCaptureDevice = 0; } #endif @@ -369,7 +324,6 @@ Send sound to device if buffer isn't really the dma buffer */ void SNDDMA_Submit(void) { - SDL_UnlockAudioDevice(sdlPlaybackDevice); } /* @@ -379,7 +333,6 @@ SNDDMA_BeginPainting */ void SNDDMA_BeginPainting (void) { - SDL_LockAudioDevice(sdlPlaybackDevice); } @@ -389,8 +342,7 @@ void SNDDMA_StartCapture(void) #ifdef USE_SDL_AUDIO_CAPTURE if (sdlCaptureDevice) { - SDL_ClearQueuedAudio(sdlCaptureDevice); - SDL_PauseAudioDevice(sdlCaptureDevice, 0); + SDL_ResumeAudioDevice(sdlCaptureDevice); } #endif } @@ -399,7 +351,7 @@ int SNDDMA_AvailableCaptureSamples(void) { #ifdef USE_SDL_AUDIO_CAPTURE // divided by 2 to convert from bytes to (mono16) samples. - return sdlCaptureDevice ? (SDL_GetQueuedAudioSize(sdlCaptureDevice) / 2) : 0; + return sdlCaptureStream ? (SDL_GetAudioStreamAvailable(sdlCaptureStream) / 2) : 0; #else return 0; #endif @@ -409,9 +361,9 @@ void SNDDMA_Capture(int samples, byte *data) { #ifdef USE_SDL_AUDIO_CAPTURE // multiplied by 2 to convert from (mono16) samples to bytes. - if (sdlCaptureDevice) + if (sdlCaptureStream) { - SDL_DequeueAudio(sdlCaptureDevice, data, samples * 2); + SDL_GetAudioStreamData(sdlCaptureStream, data, samples * 2); } else #endif @@ -425,7 +377,7 @@ void SNDDMA_StopCapture(void) #ifdef USE_SDL_AUDIO_CAPTURE if (sdlCaptureDevice) { - SDL_PauseAudioDevice(sdlCaptureDevice, 1); + SDL_PauseAudioDevice(sdlCaptureDevice); } #endif } @@ -433,7 +385,7 @@ void SNDDMA_StopCapture(void) void SNDDMA_MasterGain( float val ) { #ifdef USE_SDL_AUDIO_CAPTURE - sdlMasterGain = val; + SDL_SetAudioStreamGain( sdlPlaybackStream, val ); #endif } #endif diff --git a/code/sys/sys_loadlib.h b/code/sys/sys_loadlib.h index eac0f2c769..8e515069f8 100644 --- a/code/sys/sys_loadlib.h +++ b/code/sys/sys_loadlib.h @@ -36,11 +36,11 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA # endif #else # ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" -# include "SDL_loadso.h" +# include "SDL3/SDL.h" +# include "SDL3/SDL_loadso.h" # else -# include -# include +# include +# include # endif # define Sys_LoadLibrary(f) SDL_LoadObject(f) # define Sys_UnloadLibrary(h) SDL_UnloadObject(h) diff --git a/code/sys/sys_local.h b/code/sys/sys_local.h index 69c164c586..976cd63c3d 100644 --- a/code/sys/sys_local.h +++ b/code/sys/sys_local.h @@ -25,19 +25,15 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #ifndef DEDICATED #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL_version.h" +# include "SDL3/SDL_version.h" #else -# include +# include #endif // Require a minimum version of SDL -#define MINSDL_MAJOR 2 -#define MINSDL_MINOR 0 -#if SDL_VERSION_ATLEAST( 2, 0, 5 ) -#define MINSDL_PATCH 5 -#else -#define MINSDL_PATCH 0 -#endif +#define MINSDL_MAJOR 3 +#define MINSDL_MINOR 2 +#define MINSDL_MICRO 0 #endif // Console diff --git a/code/sys/sys_main.c b/code/sys/sys_main.c index 0becb8382c..ad5ab2fd2e 100644 --- a/code/sys/sys_main.c +++ b/code/sys/sys_main.c @@ -37,11 +37,13 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #ifndef DEDICATED #ifdef USE_INTERNAL_SDL_HEADERS -# include "SDL.h" -# include "SDL_cpuinfo.h" +# include "SDL3/SDL.h" +# include "SDL3/SDL_main.h" +# include "SDL3/SDL_cpuinfo.h" #else -# include -# include +# include +# include +# include #endif #endif @@ -341,8 +343,6 @@ cpuFeatures_t Sys_GetProcessorFeatures( void ) cpuFeatures_t features = 0; #ifndef DEDICATED - if( SDL_HasRDTSC( ) ) features |= CF_RDTSC; - if( SDL_Has3DNow( ) ) features |= CF_3DNOW; if( SDL_HasMMX( ) ) features |= CF_MMX; if( SDL_HasSSE( ) ) features |= CF_SSE; if( SDL_HasSSE2( ) ) features |= CF_SSE2; @@ -602,8 +602,9 @@ void *Sys_LoadGameDll(const char *name, vmMainProc *entryPoint, intptr_t (*systemcalls)(intptr_t, ...)) { + typedef void (*dllEntry_t)(intptr_t (*syscallptr)(intptr_t, ...)); + dllEntry_t dllEntry; void *libHandle; - void (*dllEntry)(intptr_t (*syscallptr)(intptr_t, ...)); assert(name); @@ -622,8 +623,8 @@ void *Sys_LoadGameDll(const char *name, return NULL; } - dllEntry = Sys_LoadFunction( libHandle, "dllEntry" ); - *entryPoint = Sys_LoadFunction( libHandle, "vmMain" ); + dllEntry = (dllEntry_t)Sys_LoadFunction( libHandle, "dllEntry" ); + *entryPoint = (vmMainProc)Sys_LoadFunction( libHandle, "vmMain" ); if ( !*entryPoint || !dllEntry ) { @@ -797,25 +798,27 @@ int main( int argc, char **argv ) // SDL version check // Compile time -# if !SDL_VERSION_ATLEAST(MINSDL_MAJOR,MINSDL_MINOR,MINSDL_PATCH) +# if !SDL_VERSION_ATLEAST(MINSDL_MAJOR,MINSDL_MINOR,MINSDL_MICRO) # error A more recent version of SDL is required # endif // Run time - SDL_version ver; - SDL_GetVersion( &ver ); + int version = SDL_GetVersion(); + int major = SDL_VERSIONNUM_MAJOR(version); + int minor = SDL_VERSIONNUM_MINOR(version); + int micro = SDL_VERSIONNUM_MICRO(version); #define MINSDL_VERSION \ XSTRING(MINSDL_MAJOR) "." \ XSTRING(MINSDL_MINOR) "." \ - XSTRING(MINSDL_PATCH) + XSTRING(MINSDL_MICRO) - if( SDL_VERSIONNUM( ver.major, ver.minor, ver.patch ) < - SDL_VERSIONNUM( MINSDL_MAJOR, MINSDL_MINOR, MINSDL_PATCH ) ) + if( SDL_VERSIONNUM( major, minor, micro ) < + SDL_VERSIONNUM( MINSDL_MAJOR, MINSDL_MINOR, MINSDL_MICRO ) ) { Sys_Dialog( DT_ERROR, va( "SDL version " MINSDL_VERSION " or greater is required, " "but only version %d.%d.%d was found. You may be able to obtain a more recent copy " - "from https://www.libsdl.org/.", ver.major, ver.minor, ver.patch ), "SDL Library Too Old" ); + "from https://www.libsdl.org/.", major, minor, micro ), "SDL Library Too Old" ); Sys_Exit( 1 ); } diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL.h b/code/thirdparty/SDL2-2.32.8/include/SDL.h deleted file mode 100644 index 0fe0713391..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL.h +++ /dev/null @@ -1,234 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * \file SDL.h - * - * Main include header for the SDL library - */ - -#ifndef SDL_h_ -#define SDL_h_ - -#include "SDL_main.h" -#include "SDL_stdinc.h" -#include "SDL_assert.h" -#include "SDL_atomic.h" -#include "SDL_audio.h" -#include "SDL_clipboard.h" -#include "SDL_cpuinfo.h" -#include "SDL_endian.h" -#include "SDL_error.h" -#include "SDL_events.h" -#include "SDL_filesystem.h" -#include "SDL_gamecontroller.h" -#include "SDL_guid.h" -#include "SDL_haptic.h" -#include "SDL_hidapi.h" -#include "SDL_hints.h" -#include "SDL_joystick.h" -#include "SDL_loadso.h" -#include "SDL_log.h" -#include "SDL_messagebox.h" -#include "SDL_metal.h" -#include "SDL_mutex.h" -#include "SDL_power.h" -#include "SDL_render.h" -#include "SDL_rwops.h" -#include "SDL_sensor.h" -#include "SDL_shape.h" -#include "SDL_system.h" -#include "SDL_thread.h" -#include "SDL_timer.h" -#include "SDL_version.h" -#include "SDL_video.h" -#include "SDL_locale.h" -#include "SDL_misc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* WIKI CATEGORY: Init */ - -/* As of version 0.5, SDL is loaded dynamically into the application */ - -/** - * \name SDL_INIT_* - * - * These are the flags which may be passed to SDL_Init(). You should - * specify the subsystems which you will be using in your application. - */ -/* @{ */ -#define SDL_INIT_TIMER 0x00000001u -#define SDL_INIT_AUDIO 0x00000010u -#define SDL_INIT_VIDEO 0x00000020u /**< SDL_INIT_VIDEO implies SDL_INIT_EVENTS */ -#define SDL_INIT_JOYSTICK 0x00000200u /**< SDL_INIT_JOYSTICK implies SDL_INIT_EVENTS */ -#define SDL_INIT_HAPTIC 0x00001000u -#define SDL_INIT_GAMECONTROLLER 0x00002000u /**< SDL_INIT_GAMECONTROLLER implies SDL_INIT_JOYSTICK */ -#define SDL_INIT_EVENTS 0x00004000u -#define SDL_INIT_SENSOR 0x00008000u -#define SDL_INIT_NOPARACHUTE 0x00100000u /**< compatibility; this flag is ignored. */ -#define SDL_INIT_EVERYTHING ( \ - SDL_INIT_TIMER | SDL_INIT_AUDIO | SDL_INIT_VIDEO | SDL_INIT_EVENTS | \ - SDL_INIT_JOYSTICK | SDL_INIT_HAPTIC | SDL_INIT_GAMECONTROLLER | SDL_INIT_SENSOR \ - ) -/* @} */ - -/** - * Initialize the SDL library. - * - * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the - * two may be used interchangeably. Though for readability of your code - * SDL_InitSubSystem() might be preferred. - * - * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread) - * subsystems are initialized by default. Message boxes - * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the - * video subsystem, in hopes of being useful in showing an error dialog when - * SDL_Init fails. You must specifically initialize other subsystems if you - * use them in your application. - * - * Logging (such as SDL_Log) works without initialization, too. - * - * `flags` may be any of the following OR'd together: - * - * - `SDL_INIT_TIMER`: timer subsystem - * - `SDL_INIT_AUDIO`: audio subsystem - * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem - * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the - * events subsystem - * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem - * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically - * initializes the joystick subsystem - * - `SDL_INIT_EVENTS`: events subsystem - * - `SDL_INIT_EVERYTHING`: all of the above subsystems - * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored - * - * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem() - * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or - * call SDL_Quit() to force shutdown). If a subsystem is already loaded then - * this call will increase the ref-count and return. - * - * \param flags subsystem initialization flags. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_InitSubSystem - * \sa SDL_Quit - * \sa SDL_SetMainReady - * \sa SDL_WasInit - */ -extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags); - -/** - * Compatibility function to initialize the SDL library. - * - * In SDL2, this function and SDL_Init() are interchangeable. - * - * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Init - * \sa SDL_Quit - * \sa SDL_QuitSubSystem - */ -extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags); - -/** - * Shut down specific SDL subsystems. - * - * If you start a subsystem using a call to that subsystem's init function - * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(), - * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use - * that subsystem's quit function (SDL_VideoQuit()) directly instead. But - * generally, you should not be using those functions directly anyhow; use - * SDL_Init() instead. - * - * You still need to call SDL_Quit() even if you close all open subsystems - * with SDL_QuitSubSystem(). - * - * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_InitSubSystem - * \sa SDL_Quit - */ -extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags); - -/** - * Get a mask of the specified subsystems which are currently initialized. - * - * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. - * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it - * returns the initialization status of the specified subsystems. - * - * The return value does not include SDL_INIT_NOPARACHUTE. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Init - * \sa SDL_InitSubSystem - */ -extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags); - -/** - * Clean up all initialized subsystems. - * - * You should call this function even if you have already shutdown each - * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this - * function even in the case of errors in initialization. - * - * If you start a subsystem using a call to that subsystem's init function - * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(), - * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut - * it down before calling SDL_Quit(). But generally, you should not be using - * those functions directly anyhow; use SDL_Init() instead. - * - * You can use this function with atexit() to ensure that it is run when your - * application is shutdown, but it is not wise to do this from a library or - * other dynamically loaded code. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Init - * \sa SDL_QuitSubSystem - */ -extern DECLSPEC void SDLCALL SDL_Quit(void); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_assert.h b/code/thirdparty/SDL2-2.32.8/include/SDL_assert.h deleted file mode 100644 index fea3f90f04..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_assert.h +++ /dev/null @@ -1,324 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_assert_h_ -#define SDL_assert_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -#ifndef SDL_ASSERT_LEVEL -#ifdef SDL_DEFAULT_ASSERT_LEVEL -#define SDL_ASSERT_LEVEL SDL_DEFAULT_ASSERT_LEVEL -#elif defined(_DEBUG) || defined(DEBUG) || \ - (defined(__GNUC__) && !defined(__OPTIMIZE__)) -#define SDL_ASSERT_LEVEL 2 -#else -#define SDL_ASSERT_LEVEL 1 -#endif -#endif /* SDL_ASSERT_LEVEL */ - -/* -These are macros and not first class functions so that the debugger breaks -on the assertion line and not in some random guts of SDL, and so each -assert can have unique static variables associated with it. -*/ - -#if defined(_MSC_VER) -/* Don't include intrin.h here because it contains C++ code */ - extern void __cdecl __debugbreak(void); - #define SDL_TriggerBreakpoint() __debugbreak() -#elif _SDL_HAS_BUILTIN(__builtin_debugtrap) - #define SDL_TriggerBreakpoint() __builtin_debugtrap() -#elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) ) - #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) -#elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) - #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\n\t" ) -#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */ - #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) -#elif defined(__APPLE__) && defined(__arm__) - #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) -#elif defined(_WIN32) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__arm64__) || defined(__aarch64__)) ) - #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #0xF000\n\t" ) -#elif defined(__386__) && defined(__WATCOMC__) - #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } -#elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) - #include - #define SDL_TriggerBreakpoint() raise(SIGTRAP) -#else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() -#endif - -#if 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 -#define SDL_FILE __FILE__ -#define SDL_LINE __LINE__ - -/* -sizeof (x) makes the compiler still parse the expression even without -assertions enabled, so the code is always checked at compile time, but -doesn't actually generate code for it, so there are no side effects or -expensive checks at run time, just the constant size of what x WOULD be, -which presumably gets optimized out as unused. -This also solves the problem of... - - int somevalue = blah(); - SDL_assert(somevalue == 1); - -...which would cause compiles to complain that somevalue is unused if we -disable assertions. -*/ - -/* "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 - -#define SDL_disabled_assert(condition) \ - do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) - -typedef enum -{ - SDL_ASSERTION_RETRY, /**< Retry the assert immediately. */ - SDL_ASSERTION_BREAK, /**< Make the debugger trigger a breakpoint. */ - SDL_ASSERTION_ABORT, /**< Terminate the program. */ - SDL_ASSERTION_IGNORE, /**< Ignore the assert. */ - SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */ -} SDL_AssertState; - -typedef struct SDL_AssertData -{ - int always_ignore; - unsigned int trigger_count; - const char *condition; - const char *filename; - int linenum; - const char *function; - const struct SDL_AssertData *next; -} SDL_AssertData; - -/* Never call this directly. Use the SDL_assert* macros. */ -extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *, - const char *, - const char *, int) -#if defined(__clang__) -#if __has_feature(attribute_analyzer_noreturn) -/* this tells Clang's static analysis that we're a custom assert function, - and that the analyzer should assume the condition was always true past this - SDL_assert test. */ - __attribute__((analyzer_noreturn)) -#endif -#endif -; - -/* 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. -*/ -#define SDL_enabled_assert(condition) \ - do { \ - while ( !(condition) ) { \ - static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \ - const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \ - if (sdl_assert_state == SDL_ASSERTION_RETRY) { \ - continue; /* go again. */ \ - } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \ - SDL_TriggerBreakpoint(); \ - } \ - break; /* not retrying. */ \ - } \ - } while (SDL_NULL_WHILE_LOOP_CONDITION) - -/* Enable various levels of assertions. */ -#if SDL_ASSERT_LEVEL == 0 /* assertions disabled */ -# define SDL_assert(condition) SDL_disabled_assert(condition) -# define SDL_assert_release(condition) SDL_disabled_assert(condition) -# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) -#elif SDL_ASSERT_LEVEL == 1 /* release settings. */ -# define SDL_assert(condition) SDL_disabled_assert(condition) -# define SDL_assert_release(condition) SDL_enabled_assert(condition) -# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) -#elif SDL_ASSERT_LEVEL == 2 /* normal settings. */ -# define SDL_assert(condition) SDL_enabled_assert(condition) -# define SDL_assert_release(condition) SDL_enabled_assert(condition) -# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) -#elif SDL_ASSERT_LEVEL == 3 /* paranoid settings. */ -# define SDL_assert(condition) SDL_enabled_assert(condition) -# define SDL_assert_release(condition) SDL_enabled_assert(condition) -# define SDL_assert_paranoid(condition) SDL_enabled_assert(condition) -#else -# error Unknown assertion level. -#endif - -/* this assertion is never disabled at any level. */ -#define SDL_assert_always(condition) SDL_enabled_assert(condition) - - -/** - * A callback that fires when an SDL assertion fails. - * - * \param data a pointer to the SDL_AssertData structure corresponding to the - * current assertion. - * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). - * \returns an SDL_AssertState value indicating how to handle the failure. - */ -typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( - const SDL_AssertData* data, void* userdata); - -/** - * Set an application-defined assertion handler. - * - * This function allows an application to show its own assertion UI and/or - * force the response to an assertion failure. If the application doesn't - * provide this, SDL will try to do the right thing, popping up a - * system-specific GUI dialog, and probably minimizing any fullscreen windows. - * - * This callback may fire from any thread, but it runs wrapped in a mutex, so - * it will only fire from one thread at a time. - * - * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! - * - * \param handler the SDL_AssertionHandler function to call when an assertion - * fails or NULL for the default handler. - * \param userdata a pointer that is passed to `handler`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAssertionHandler - */ -extern DECLSPEC void SDLCALL SDL_SetAssertionHandler( - SDL_AssertionHandler handler, - void *userdata); - -/** - * Get the default assertion handler. - * - * This returns the function pointer that is called by default when an - * assertion is triggered. This is an internal function provided by SDL, that - * is used for assertions when SDL_SetAssertionHandler() hasn't been used to - * provide a different function. - * - * \returns the default SDL_AssertionHandler that is called when an assert - * triggers. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_GetAssertionHandler - */ -extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void); - -/** - * Get the current assertion handler. - * - * This returns the function pointer that is called when an assertion is - * triggered. This is either the value last passed to - * SDL_SetAssertionHandler(), or if no application-specified function is set, - * is equivalent to calling SDL_GetDefaultAssertionHandler(). - * - * The parameter `puserdata` is a pointer to a void*, which will store the - * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value - * will always be NULL for the default handler. If you don't care about this - * data, it is safe to pass a NULL pointer to this function to ignore it. - * - * \param puserdata pointer which is filled with the "userdata" pointer that - * was passed to SDL_SetAssertionHandler(). - * \returns the SDL_AssertionHandler that is called when an assert triggers. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_SetAssertionHandler - */ -extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata); - -/** - * Get a list of all assertion failures. - * - * This function gets all assertions triggered since the last call to - * SDL_ResetAssertionReport(), or the start of the program. - * - * The proper way to examine this data looks something like this: - * - * ```c - * const SDL_AssertData *item = SDL_GetAssertionReport(); - * while (item) { - * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", - * item->condition, item->function, item->filename, - * item->linenum, item->trigger_count, - * item->always_ignore ? "yes" : "no"); - * item = item->next; - * } - * ``` - * - * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ResetAssertionReport - */ -extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); - -/** - * Clear the list of all assertion failures. - * - * This function will clear the list of all assertions triggered up to that - * point. Immediately following this call, SDL_GetAssertionReport will return - * no items. In addition, any previously-triggered assertions will be reset to - * a trigger_count of zero, and their always_ignore state will be false. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAssertionReport - */ -extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); - - -/* these had wrong naming conventions until 2.0.4. Please update your app! */ -#define SDL_assert_state SDL_AssertState -#define SDL_assert_data SDL_AssertData - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_assert_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_atomic.h b/code/thirdparty/SDL2-2.32.8/include/SDL_atomic.h deleted file mode 100644 index 226ec7c67f..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_atomic.h +++ /dev/null @@ -1,408 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryAtomic - * - * Atomic operations. - * - * IMPORTANT: If you are not an expert in concurrent lockless programming, you - * should not be using any functions in this file. You should be protecting - * your data structures with full mutexes instead. - * - * ***Seriously, here be dragons!*** - * - * You can find out a little more about lockless programming and the subtle - * issues that can arise here: - * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming - * - * There's also lots of good information here: - * - * - https://www.1024cores.net/home/lock-free-algorithms - * - https://preshing.com/ - * - * These operations may or may not actually be implemented using processor - * specific atomic operations. When possible they are implemented as true - * processor specific atomic operations. When that is not possible the are - * implemented using locks that *do* use the available atomic operations. - * - * All of the atomic operations that modify memory are full memory barriers. - */ - -#ifndef SDL_atomic_h_ -#define SDL_atomic_h_ - -#include "SDL_stdinc.h" -#include "SDL_platform.h" - -#include "begin_code.h" - -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \name SDL AtomicLock - * - * The atomic locks are efficient spinlocks using CPU instructions, - * but are vulnerable to starvation and can spin forever if a thread - * holding a lock has been terminated. For this reason you should - * minimize the code executed inside an atomic lock and never do - * expensive things like API or system calls while holding them. - * - * The atomic locks are not safe to lock recursively. - * - * Porting Note: - * The spin lock functions and type are required and can not be - * emulated because they are used in the atomic emulation code. - */ -/* @{ */ - -typedef int SDL_SpinLock; - -/** - * Try to lock a spin lock by setting it to a non-zero value. - * - * ***Please note that spinlocks are dangerous if you don't know what you're - * doing. Please be careful using any sort of spinlock!*** - * - * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AtomicLock - * \sa SDL_AtomicUnlock - */ -extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock); - -/** - * Lock a spin lock by setting it to a non-zero value. - * - * ***Please note that spinlocks are dangerous if you don't know what you're - * doing. Please be careful using any sort of spinlock!*** - * - * \param lock a pointer to a lock variable. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AtomicTryLock - * \sa SDL_AtomicUnlock - */ -extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock); - -/** - * Unlock a spin lock by setting it to 0. - * - * Always returns immediately. - * - * ***Please note that spinlocks are dangerous if you don't know what you're - * doing. Please be careful using any sort of spinlock!*** - * - * \param lock a pointer to a lock variable. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AtomicLock - * \sa SDL_AtomicTryLock - */ -extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock); - -/* @} *//* SDL AtomicLock */ - - -/** - * The compiler barrier prevents the compiler from reordering - * reads and writes to globally visible variables across the call. - */ -#if defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) -void _ReadWriteBarrier(void); -#pragma intrinsic(_ReadWriteBarrier) -#define SDL_CompilerBarrier() _ReadWriteBarrier() -#elif (defined(__GNUC__) && !defined(__EMSCRIPTEN__)) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) -/* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */ -#define SDL_CompilerBarrier() __asm__ __volatile__ ("" : : : "memory") -#elif defined(__WATCOMC__) -extern __inline void SDL_CompilerBarrier(void); -#pragma aux SDL_CompilerBarrier = "" parm [] modify exact []; -#else -#define SDL_CompilerBarrier() \ -{ SDL_SpinLock _tmp = 0; SDL_AtomicLock(&_tmp); SDL_AtomicUnlock(&_tmp); } -#endif - -/** - * 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. - * - * A typical pattern would be for thread A to write some data and a flag, and - * for thread B to read the flag and get the data. In this case you would - * insert a release barrier between writing the data and the flag, - * guaranteeing that the data write completes no later than the flag is - * written, and you would insert an acquire barrier between reading the flag - * and reading the data, to ensure that all the reads associated with the flag - * have completed. - * - * In this pattern you should always see a release barrier paired with an - * acquire barrier and you should gate the data reads/writes with a single - * flag variable. - * - * For more information on these semantics, take a look at the blog post: - * http://preshing.com/20120913/acquire-and-release-semantics - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); -extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); - -#if 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__) -#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") -#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") -#elif defined(__GNUC__) && defined(__arm__) -#if 0 /* defined(__LINUX__) || defined(__ANDROID__) */ -/* Information from: - https://chromium.googlesource.com/chromium/chromium/+/trunk/base/atomicops_internals_arm_gcc.h#19 - - The Linux kernel provides a helper function which provides the right code for a memory barrier, - hard-coded at address 0xffff0fa0 -*/ -typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#elif 0 /* defined(__QNXNTO__) */ -#include - -#define SDL_MemoryBarrierRelease() __cpu_membarrier() -#define SDL_MemoryBarrierAcquire() __cpu_membarrier() -#else -#if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) -#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") -#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") -#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) -#ifdef __thumb__ -/* The mcr instruction isn't available in thumb mode, use real functions */ -#define SDL_MEMORY_BARRIER_USES_FUNCTION -#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() -#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -#else -#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") -#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") -#endif /* __thumb__ */ -#else -#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("" : : : "memory") -#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("" : : : "memory") -#endif /* __LINUX__ || __ANDROID__ */ -#endif /* __GNUC__ && __arm__ */ -#else -#if (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) -/* This is correct for all CPUs on Solaris when using Solaris Studio 12.1+. */ -#include -#define SDL_MemoryBarrierRelease() __machine_rel_barrier() -#define SDL_MemoryBarrierAcquire() __machine_acq_barrier() -#else -/* This is correct for the x86 and x64 CPUs, and we'll expand this over time. */ -#define SDL_MemoryBarrierRelease() SDL_CompilerBarrier() -#define SDL_MemoryBarrierAcquire() SDL_CompilerBarrier() -#endif -#endif - -/* "REP NOP" is PAUSE, coded for tools that don't know it by that name. */ -#if (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__) - #define SDL_CPUPauseInstruction() __asm__ __volatile__("yield" ::: "memory") -#elif (defined(__powerpc__) || defined(__powerpc64__)) - #define SDL_CPUPauseInstruction() __asm__ __volatile__("or 27,27,27"); -#elif defined(_MSC_VER) && (defined(_M_IX86) || defined(_M_X64)) - #define SDL_CPUPauseInstruction() _mm_pause() /* this is actually "rep nop" and not a SIMD instruction. No inline asm in MSVC x86-64! */ -#elif defined(_MSC_VER) && (defined(_M_ARM) || defined(_M_ARM64)) - #define SDL_CPUPauseInstruction() __yield() -#elif defined(__WATCOMC__) && defined(__386__) - extern __inline void SDL_CPUPauseInstruction(void); - #pragma aux SDL_CPUPauseInstruction = ".686p" ".xmm2" "pause" -#else - #define SDL_CPUPauseInstruction() -#endif - - -/** - * A type representing an atomic integer value. - * - * It is a struct so people don't accidentally use numeric operations on it. - */ -typedef struct SDL_atomic_t { - int value; -} SDL_atomic_t; - -/** - * Set an atomic variable to a new value if it is currently an old value. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to an SDL_atomic_t variable to be modified. - * \param oldval the old value. - * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AtomicCASPtr - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - */ -extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval); - -/** - * Set an atomic variable to a value. - * - * This function also acts as a full memory barrier. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to an SDL_atomic_t variable to be modified. - * \param v the desired value. - * \returns the previous value of the atomic variable. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_AtomicGet - */ -extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v); - -/** - * Get the value of an atomic variable. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to an SDL_atomic_t variable. - * \returns the current value of an atomic variable. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_AtomicSet - */ -extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); - -/** - * Add to an atomic variable. - * - * This function also acts as a full memory barrier. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to an SDL_atomic_t variable to be modified. - * \param v the desired value to add. - * \returns the previous value of the atomic variable. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_AtomicDecRef - * \sa SDL_AtomicIncRef - */ -extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v); - -/** - * \brief Increment an atomic variable used as a reference count. - */ -#ifndef SDL_AtomicIncRef -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) -#endif - -/** - * \brief Decrement an atomic variable used as a reference count. - * - * \return SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise - */ -#ifndef SDL_AtomicDecRef -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) -#endif - -/** - * Set a pointer to a new value if it is currently an old value. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to a pointer. - * \param oldval the old pointer value. - * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AtomicCAS - * \sa SDL_AtomicGetPtr - * \sa SDL_AtomicSetPtr - */ -extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval); - -/** - * Set a pointer to a value atomically. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to a pointer. - * \param v the desired pointer value. - * \returns the previous value of the pointer. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_AtomicCASPtr - * \sa SDL_AtomicGetPtr - */ -extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v); - -/** - * Get the value of a pointer atomically. - * - * ***Note: If you don't know what this function is for, you shouldn't use - * it!*** - * - * \param a a pointer to a pointer. - * \returns the current value of a pointer. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_AtomicCASPtr - * \sa SDL_AtomicSetPtr - */ -extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif - -#include "close_code.h" - -#endif /* SDL_atomic_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_audio.h b/code/thirdparty/SDL2-2.32.8/include/SDL_audio.h deleted file mode 100644 index cb76e93e43..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_audio.h +++ /dev/null @@ -1,1502 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* !!! FIXME: several functions in here need Doxygen comments. */ - -/** - * # CategoryAudio - * - * Access to the raw audio mixing buffer for the SDL library. - */ - -#ifndef SDL_audio_h_ -#define SDL_audio_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_endian.h" -#include "SDL_mutex.h" -#include "SDL_thread.h" -#include "SDL_rwops.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Audio format flags. - * - * These are what the 16 bits in SDL_AudioFormat currently mean... - * (Unspecified bits are always zero). - * - * ``` - * ++-----------------------sample is signed if set - * || - * || ++-----------sample is bigendian if set - * || || - * || || ++---sample is float if set - * || || || - * || || || +---sample bit size---+ - * || || || | | - * 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 - * ``` - * - * There are macros in SDL 2.0 and later to query these bits. - */ -typedef Uint16 SDL_AudioFormat; - -/** - * \name Audio flags - */ -/* @{ */ - -#define SDL_AUDIO_MASK_BITSIZE (0xFF) -#define SDL_AUDIO_MASK_DATATYPE (1<<8) -#define SDL_AUDIO_MASK_ENDIAN (1<<12) -#define SDL_AUDIO_MASK_SIGNED (1<<15) -#define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE) -#define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE) -#define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN) -#define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED) -#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) -#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) -#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) - -/** - * \name Audio format flags - * - * Defaults to LSB byte order. - */ -/* @{ */ -#define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ -#define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ -#define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ -#define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ -#define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ -#define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ -#define AUDIO_U16 AUDIO_U16LSB -#define AUDIO_S16 AUDIO_S16LSB -/* @} */ - -/** - * \name int32 support - */ -/* @{ */ -#define AUDIO_S32LSB 0x8020 /**< 32-bit integer samples */ -#define AUDIO_S32MSB 0x9020 /**< As above, but big-endian byte order */ -#define AUDIO_S32 AUDIO_S32LSB -/* @} */ - -/** - * \name float32 support - */ -/* @{ */ -#define AUDIO_F32LSB 0x8120 /**< 32-bit floating point samples */ -#define AUDIO_F32MSB 0x9120 /**< As above, but big-endian byte order */ -#define AUDIO_F32 AUDIO_F32LSB -/* @} */ - -/** - * \name Native audio byte ordering - */ -/* @{ */ -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define AUDIO_U16SYS AUDIO_U16LSB -#define AUDIO_S16SYS AUDIO_S16LSB -#define AUDIO_S32SYS AUDIO_S32LSB -#define AUDIO_F32SYS AUDIO_F32LSB -#else -#define AUDIO_U16SYS AUDIO_U16MSB -#define AUDIO_S16SYS AUDIO_S16MSB -#define AUDIO_S32SYS AUDIO_S32MSB -#define AUDIO_F32SYS AUDIO_F32MSB -#endif -/* @} */ - -/** - * \name Allow change flags - * - * Which audio format changes are allowed when opening a device. - */ -/* @{ */ -#define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001 -#define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002 -#define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004 -#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE 0x00000008 -#define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE) -/* @} */ - -/* @} *//* Audio flags */ - -/** - * This function is called when the audio device needs more data. - * - * \param userdata An application-specific parameter saved in the - * SDL_AudioSpec structure. - * \param stream A pointer to the audio data buffer. - * \param len Length of **stream** in bytes. - */ -typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, - int len); - -/** - * The calculated values in this structure are calculated by SDL_OpenAudio(). - * - * For multi-channel audio, the default SDL channel mapping is: - * - * ``` - * 2: FL FR (stereo) - * 3: FL FR LFE (2.1 surround) - * 4: FL FR BL BR (quad) - * 5: FL FR LFE BL BR (4.1 surround) - * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) - * 7: FL FR FC LFE BC SL SR (6.1 surround) - * 8: FL FR FC LFE BL BR SL SR (7.1 surround) - * ``` - */ -typedef struct SDL_AudioSpec -{ - int freq; /**< DSP frequency -- samples per second */ - SDL_AudioFormat format; /**< Audio data format */ - Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ - Uint8 silence; /**< Audio buffer silence value (calculated) */ - Uint16 samples; /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */ - Uint16 padding; /**< Necessary for some compile environments */ - Uint32 size; /**< Audio buffer size in bytes (calculated) */ - SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */ - void *userdata; /**< Userdata passed to callback (ignored for NULL callbacks). */ -} SDL_AudioSpec; - - -struct SDL_AudioCVT; -typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, - SDL_AudioFormat format); - -/** - * Upper limit of filters in SDL_AudioCVT - * - * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is - * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one - * of which is the terminating NULL pointer. - */ -#define SDL_AUDIOCVT_MAX_FILTERS 9 - -/** - * \struct SDL_AudioCVT - * \brief A structure to hold a set of audio conversion filters and buffers. - * - * Note that various parts of the conversion pipeline can take advantage - * of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require - * you to pass it aligned data, but can possibly run much faster if you - * set both its (buf) field to a pointer that is aligned to 16 bytes, and its - * (len) field to something that's a multiple of 16, if possible. - */ -#if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__) -/* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't - pad it out to 88 bytes to guarantee ABI compatibility between compilers. - This is not a concern on CHERI architectures, where pointers must be stored - at aligned locations otherwise they will become invalid, and thus structs - containing pointers cannot be packed without giving a warning or error. - vvv - The next time we rev the ABI, make sure to size the ints and add padding. -*/ -#define SDL_AUDIOCVT_PACKED __attribute__((packed)) -#else -#define SDL_AUDIOCVT_PACKED -#endif -/* */ -typedef struct SDL_AudioCVT -{ - int needed; /**< Set to 1 if conversion possible */ - SDL_AudioFormat src_format; /**< Source audio format */ - SDL_AudioFormat dst_format; /**< Target audio format */ - double rate_incr; /**< Rate conversion increment */ - Uint8 *buf; /**< Buffer to hold entire audio data */ - int len; /**< Length of original audio buffer */ - int len_cvt; /**< Length of converted audio buffer */ - int len_mult; /**< buffer must be len*len_mult big */ - double len_ratio; /**< Given len, final size is len*len_ratio */ - SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1]; /**< NULL-terminated list of filter functions */ - int filter_index; /**< Current audio conversion function */ -} SDL_AUDIOCVT_PACKED SDL_AudioCVT; - - -/* 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. - * - * This function returns a hardcoded number. This never returns a negative - * value; if there are no drivers compiled into this build of SDL, this - * function returns zero. The presence of a driver in this list does not mean - * it will function, it just means SDL is capable of interacting with that - * interface. For example, a build of SDL might have esound support, but if - * there's no esound server available, SDL's esound driver would fail if used. - * - * By default, SDL tries all drivers, in its preferred order, until one is - * found to be usable. - * - * \returns the number of built-in audio drivers. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAudioDriver - */ -extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); - -/** - * Use this function to get the name of a built in audio driver. - * - * The list of audio drivers is given in the order that they are normally - * initialized by default; the drivers that seem more reasonable to choose - * first (as far as the SDL developers believe) are earlier in the list. - * - * The names of drivers are all simple, low-ASCII identifiers, like "alsa", - * "coreaudio" or "xaudio2". These never have Unicode characters, and are not - * meant to be proper names. - * - * \param index the index of the audio driver; the value ranges from 0 to - * SDL_GetNumAudioDrivers() - 1. - * \returns the name of the audio driver at the requested index, or NULL if an - * invalid index was specified. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumAudioDrivers - */ -extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); -/* @} */ - -/** - * \name Initialization and cleanup - * - * \internal These functions are used internally, and should not be used unless - * you have a specific need to specify the audio driver you want to - * use. You should normally use SDL_Init() or SDL_InitSubSystem(). - */ -/* @{ */ - -/** - * Use this function to initialize a particular audio driver. - * - * This function is used internally, and should not be used unless you have a - * specific need to designate the audio driver you want to use. You should - * normally use SDL_Init() or SDL_InitSubSystem(). - * - * \param driver_name the name of the desired audio driver. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AudioQuit - */ -extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); - -/** - * Use this function to shut down audio if you initialized it with - * SDL_AudioInit(). - * - * This function is used internally, and should not be used unless you have a - * specific need to specify the audio driver you want to use. You should - * normally use SDL_Quit() or SDL_QuitSubSystem(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AudioInit - */ -extern DECLSPEC void SDLCALL SDL_AudioQuit(void); -/* @} */ - -/** - * Get the name of the current audio driver. - * - * The returned string points to internal static memory and thus never becomes - * invalid, even if you quit the audio subsystem and initialize a new driver - * (although such a case would return a different static string from another - * call to this function, of course). As such, you should not modify or free - * the returned string. - * - * \returns the name of the current audio driver or NULL if no driver has been - * initialized. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AudioInit - */ -extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); - -/** - * This function is a legacy means of opening the audio device. - * - * This function remains for compatibility with SDL 1.2, but also because it's - * slightly easier to use than the new functions in SDL 2.0. The new, more - * powerful, and preferred way to do this is SDL_OpenAudioDevice(). - * - * This function is roughly equivalent to: - * - * ```c - * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE); - * ``` - * - * With two notable exceptions: - * - * - If `obtained` is NULL, we use `desired` (and allow no changes), which - * means desired will be modified to have the correct values for silence, - * etc, and SDL will convert any differences between your app's specific - * request and the hardware behind the scenes. - * - The return value is always success or failure, and not a device ID, which - * means you can only have one device open at a time with this function. - * - * \param desired an SDL_AudioSpec structure representing the desired output - * format. Please refer to the SDL_OpenAudioDevice - * documentation for details on how to prepare this structure. - * \param obtained an SDL_AudioSpec structure filled in with the actual - * parameters, or NULL. - * \returns 0 if successful, placing the actual hardware parameters in the - * structure pointed to by `obtained`. - * - * If `obtained` is NULL, the audio data passed to the callback - * function will be guaranteed to be in the requested format, and - * will be automatically converted to the actual hardware audio - * format if necessary. If `obtained` is NULL, `desired` will have - * fields modified. - * - * This function returns a negative error code on failure to open the - * audio device or failure to set up the audio thread; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CloseAudio - * \sa SDL_LockAudio - * \sa SDL_PauseAudio - * \sa SDL_UnlockAudio - */ -extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, - SDL_AudioSpec * obtained); - -/** - * SDL Audio Device IDs. - * - * A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL - * audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls - * always returns devices >= 2 on success. The legacy calls are good both for - * backwards compatibility and when you don't care about multiple, specific, - * or capture devices. - */ -typedef Uint32 SDL_AudioDeviceID; - -/** - * Get the number of built-in audio devices. - * - * This function is only valid after successfully initializing the audio - * subsystem. - * - * Note that audio capture support is not implemented as of SDL 2.0.4, so the - * `iscapture` parameter is for future expansion and should always be zero for - * now. - * - * This function will return -1 if an explicit list of devices can't be - * determined. Returning -1 is not an error. For example, if SDL is set up to - * talk to a remote audio server, it can't list every one available on the - * Internet, but it will still allow a specific host to be specified in - * SDL_OpenAudioDevice(). - * - * In many common cases, when this function returns a value <= 0, it can still - * successfully open the default device (NULL for first argument of - * SDL_OpenAudioDevice()). - * - * This function may trigger a complete redetect of available hardware. It - * should not be called for each iteration of a loop, but rather once at the - * start of a loop: - * - * ```c - * // Don't do this: - * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++) - * - * // do this instead: - * const int count = SDL_GetNumAudioDevices(0); - * for (int i = 0; i < count; ++i) { do_something_here(); } - * ``` - * - * \param iscapture zero to request playback devices, non-zero to request - * recording devices. - * \returns the number of available devices exposed by the current driver or - * -1 if an explicit list of devices can't be determined. A return - * value of -1 does not necessarily mean an error condition. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAudioDeviceName - * \sa SDL_OpenAudioDevice - */ -extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); - -/** - * Get the human-readable name of a specific audio device. - * - * This function is only valid after successfully initializing the audio - * subsystem. The values returned by this function reflect the latest call to - * SDL_GetNumAudioDevices(); re-call that function to redetect available - * hardware. - * - * The string returned by this function is UTF-8 encoded, read-only, and - * managed internally. You are not to free it. If you need to keep the string - * for any length of time, you should make your own copy of it, as it will be - * invalid next time any of several other SDL functions are called. - * - * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1. - * \param iscapture non-zero to query the list of recording devices, zero to - * query the list of output devices. - * \returns the name of the audio device at the requested index, or NULL on - * error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumAudioDevices - * \sa SDL_GetDefaultAudioInfo - */ -extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, - int iscapture); - -/** - * Get the preferred audio format of a specific audio device. - * - * This function is only valid after a successfully initializing the audio - * subsystem. The values returned by this function reflect the latest call to - * SDL_GetNumAudioDevices(); re-call that function to redetect available - * hardware. - * - * `spec` will be filled with the sample rate, sample format, and channel - * count. - * - * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1. - * \param iscapture non-zero to query the list of recording devices, zero to - * query the list of output devices. - * \param spec The SDL_AudioSpec to be initialized by this function. - * \returns 0 on success, nonzero on error. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_GetNumAudioDevices - * \sa SDL_GetDefaultAudioInfo - */ -extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, - int iscapture, - SDL_AudioSpec *spec); - - -/** - * Get the name and preferred format of the default audio device. - * - * Some (but not all!) platforms have an isolated mechanism to get information - * about the "default" device. This can actually be a completely different - * device that's not in the list you get from SDL_GetAudioDeviceSpec(). It can - * even be a network address! (This is discussed in SDL_OpenAudioDevice().) - * - * As a result, this call is not guaranteed to be performant, as it can query - * the sound server directly every time, unlike the other query functions. You - * should call this function sparingly! - * - * `spec` will be filled with the sample rate, sample format, and channel - * count, if a default device exists on the system. If `name` is provided, - * will be filled with either a dynamically-allocated UTF-8 string or NULL. - * - * \param name A pointer to be filled with the name of the default device (can - * be NULL). Please call SDL_free() when you are done with this - * pointer! - * \param spec The SDL_AudioSpec to be initialized by this function. - * \param iscapture non-zero to query the default recording device, zero to - * query the default output device. - * \returns 0 on success, nonzero on error. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GetAudioDeviceName - * \sa SDL_GetAudioDeviceSpec - * \sa SDL_OpenAudioDevice - */ -extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name, - SDL_AudioSpec *spec, - int iscapture); - - -/** - * Open a specific audio device. - * - * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such, - * this function will never return a 1 so as not to conflict with the legacy - * function. - * - * Please note that SDL 2.0 before 2.0.5 did not support recording; as such, - * this function would fail if `iscapture` was not zero. Starting with SDL - * 2.0.5, recording is implemented and this value can be non-zero. - * - * Passing in a `device` name of NULL requests the most reasonable default - * (and is equivalent to what SDL_OpenAudio() does to choose a device). The - * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but - * some drivers allow arbitrary and driver-specific strings, such as a - * hostname/IP address for a remote audio server, or a filename in the - * diskaudio driver. - * - * An opened audio device starts out paused, and should be enabled for playing - * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio - * callback function to be called. Since the audio driver may modify the - * requested size of the audio buffer, you should allocate any local mixing - * buffers after you open the audio device. - * - * The audio callback runs in a separate thread in most cases; you can prevent - * race conditions between your callback and other threads without fully - * pausing playback with SDL_LockAudioDevice(). For more information about the - * callback, see SDL_AudioSpec. - * - * Managing the audio spec via 'desired' and 'obtained': - * - * When filling in the desired audio spec structure: - * - * - `desired->freq` should be the frequency in sample-frames-per-second (Hz). - * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc). - * - `desired->samples` is the desired size of the audio buffer, in _sample - * frames_ (with stereo output, two samples--left and right--would make a - * single sample frame). This number should be a power of two, and may be - * adjusted by the audio driver to a value more suitable for the hardware. - * Good values seem to range between 512 and 4096 inclusive, depending on - * the application and CPU speed. Smaller values reduce latency, but can - * lead to underflow if the application is doing heavy processing and cannot - * fill the audio buffer in time. Note that the number of sample frames is - * directly related to time by the following formula: `ms = - * (sampleframes*1000)/freq` - * - `desired->size` is the size in _bytes_ of the audio buffer, and is - * calculated by SDL_OpenAudioDevice(). You don't initialize this. - * - `desired->silence` is the value used to set the buffer to silence, and is - * calculated by SDL_OpenAudioDevice(). You don't initialize this. - * - `desired->callback` should be set to a function that will be called when - * the audio device is ready for more data. It is passed a pointer to the - * audio buffer, and the length in bytes of the audio buffer. This function - * usually runs in a separate thread, and so you should protect data - * structures that it accesses by calling SDL_LockAudioDevice() and - * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL - * pointer here, and call SDL_QueueAudio() with some frequency, to queue - * more audio samples to be played (or for capture devices, call - * SDL_DequeueAudio() with some frequency, to obtain audio samples). - * - `desired->userdata` is passed as the first parameter to your callback - * function. If you passed a NULL callback, this value is ignored. - * - * `allowed_changes` can have the following flags OR'd together: - * - * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE` - * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE` - * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE` - * - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE` - * - `SDL_AUDIO_ALLOW_ANY_CHANGE` - * - * These flags specify how SDL should behave when a device cannot offer a - * specific feature. If the application requests a feature that the hardware - * doesn't offer, SDL will always try to get the closest equivalent. - * - * For example, if you ask for float32 audio format, but the sound card only - * supports int16, SDL will set the hardware to int16. If you had set - * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained` - * structure. If that flag was *not* set, SDL will prepare to convert your - * callback's float32 audio to int16 before feeding it to the hardware and - * will keep the originally requested format in the `obtained` structure. - * - * The resulting audio specs, varying depending on hardware and on what - * changes were allowed, will then be written back to `obtained`. - * - * If your application can only handle one specific data format, pass a zero - * for `allowed_changes` and let SDL transparently handle any differences. - * - * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a - * driver-specific name as appropriate. NULL requests the most - * reasonable default device. - * \param iscapture non-zero to specify a device should be opened for - * recording, not playback. - * \param desired an SDL_AudioSpec structure representing the desired output - * format; see SDL_OpenAudio() for more information. - * \param obtained an SDL_AudioSpec structure filled in with the actual output - * format; see SDL_OpenAudio() for more information. - * \param allowed_changes 0, or one or more flags OR'd together. - * \returns a valid device ID that is > 0 on success or 0 on failure; call - * SDL_GetError() for more information. - * - * For compatibility with SDL 1.2, this will never return 1, since - * SDL reserves that ID for the legacy SDL_OpenAudio() function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CloseAudioDevice - * \sa SDL_GetAudioDeviceName - * \sa SDL_LockAudioDevice - * \sa SDL_OpenAudio - * \sa SDL_PauseAudioDevice - * \sa SDL_UnlockAudioDevice - */ -extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice( - const char *device, - int iscapture, - const SDL_AudioSpec *desired, - SDL_AudioSpec *obtained, - int allowed_changes); - - - -/** - * \name Audio state - * - * Get the current audio state. - */ -/* @{ */ -typedef enum -{ - SDL_AUDIO_STOPPED = 0, - SDL_AUDIO_PLAYING, - SDL_AUDIO_PAUSED -} SDL_AudioStatus; - -/** - * This function is a legacy means of querying the audio device. - * - * New programs might want to use SDL_GetAudioDeviceStatus() instead. This - * function is equivalent to calling... - * - * ```c - * SDL_GetAudioDeviceStatus(1); - * ``` - * - * ...and is only useful if you used the legacy SDL_OpenAudio() function. - * - * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAudioDeviceStatus - */ -extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); - -/** - * Use this function to get the current audio state of an audio device. - * - * \param dev the ID of an audio device previously opened with - * SDL_OpenAudioDevice(). - * \returns the SDL_AudioStatus of the specified audio device. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PauseAudioDevice - */ -extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev); -/* @} *//* Audio State */ - -/** - * \name Pause audio functions - * - * These functions pause and unpause the audio callback processing. - * They should be called with a parameter of 0 after opening the audio - * device to start playing sound. This is so you can safely initialize - * data for your callback function after opening the audio device. - * Silence will be written to the audio device during the pause. - */ -/* @{ */ - -/** - * This function is a legacy means of pausing the audio device. - * - * New programs might want to use SDL_PauseAudioDevice() instead. This - * function is equivalent to calling... - * - * ```c - * SDL_PauseAudioDevice(1, pause_on); - * ``` - * - * ...and is only useful if you used the legacy SDL_OpenAudio() function. - * - * \param pause_on non-zero to pause, 0 to unpause. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetAudioStatus - * \sa SDL_PauseAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); - -/** - * Use this function to pause and unpause audio playback on a specified - * device. - * - * This function pauses and unpauses the audio callback processing for a given - * device. Newly-opened audio devices start in the paused state, so you must - * call this function with **pause_on**=0 after opening the specified audio - * device to start playing sound. This allows you to safely initialize data - * for your callback function after opening the audio device. Silence will be - * written to the audio device while paused, and the audio callback is - * guaranteed to not be called. Pausing one device does not prevent other - * unpaused devices from running their callbacks. - * - * Pausing state does not stack; even if you pause a device several times, a - * single unpause will start the device playing again, and vice versa. This is - * different from how SDL_LockAudioDevice() works. - * - * If you just need to protect a few variables from race conditions vs your - * callback, you shouldn't pause the audio device, as it will lead to dropouts - * in the audio playback. Instead, you should use SDL_LockAudioDevice(). - * - * \param dev a device opened by SDL_OpenAudioDevice(). - * \param pause_on non-zero to pause, 0 to unpause. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, - int pause_on); -/* @} *//* Pause audio functions */ - -/** - * Load the audio data of a WAVE file into memory. - * - * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to - * be valid pointers. The entire data portion of the file is then loaded into - * memory and decoded if necessary. - * - * If `freesrc` is non-zero, the data source gets automatically closed and - * freed before the function returns. - * - * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and - * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and - * A-law and mu-law (8 bits). Other formats are currently unsupported and - * cause an error. - * - * If this function succeeds, the pointer returned by it is equal to `spec` - * and the pointer to the audio data allocated by the function is written to - * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec - * members `freq`, `channels`, and `format` are set to the values of the audio - * data in the buffer. The `samples` member is set to a sane default and all - * others are set to zero. - * - * It's necessary to use SDL_FreeWAV() to free the audio data returned in - * `audio_buf` when it is no longer used. - * - * Because of the underspecification of the .WAV format, there are many - * problematic files in the wild that cause issues with strict decoders. To - * provide compatibility with these files, this decoder is lenient in regards - * to the truncation of the file, the fact chunk, and the size of the RIFF - * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, - * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to - * tune the behavior of the loading process. - * - * Any file that is invalid (due to truncation, corruption, or wrong values in - * the headers), too big, or unsupported causes an error. Additionally, any - * critical I/O error from the data source will terminate the loading process - * with an error. The function returns NULL on error and in all cases (with - * the exception of `src` being NULL), an appropriate error message will be - * set. - * - * It is required that the data source supports seeking. - * - * Example: - * - * ```c - * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); - * ``` - * - * Note that the SDL_LoadWAV macro does this same thing for you, but in a less - * messy way: - * - * ```c - * SDL_LoadWAV("sample.wav", &spec, &buf, &len); - * ``` - * - * \param src The data source for the WAVE data. - * \param freesrc If non-zero, SDL will _always_ free the data source. - * \param spec An SDL_AudioSpec that will be filled in with the wave file's - * format details. - * \param audio_buf A pointer filled with the audio data, allocated by the - * function. - * \param audio_len A pointer filled with the length of the audio data buffer - * in bytes. - * \returns This function, if successfully called, returns `spec`, which will - * be filled with the audio data format of the wave source data. - * `audio_buf` will be filled with a pointer to an allocated buffer - * containing the audio data, and `audio_len` is filled with the - * length of that audio buffer in bytes. - * - * This function returns NULL if the .WAV file cannot be opened, uses - * an unknown data format, or is corrupt; call SDL_GetError() for - * more information. - * - * When the application is done with the data returned in - * `audio_buf`, it should call SDL_FreeWAV() to dispose of it. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeWAV - * \sa SDL_LoadWAV - */ -extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, - int freesrc, - SDL_AudioSpec * spec, - Uint8 ** audio_buf, - Uint32 * audio_len); - -/** - * Loads a WAV from a file. - * - * Compatibility convenience function. - */ -#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ - SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) - -/** - * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW(). - * - * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW() - * its data can eventually be freed with SDL_FreeWAV(). It is safe to call - * this function with a NULL pointer. - * - * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or - * SDL_LoadWAV_RW(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LoadWAV - * \sa SDL_LoadWAV_RW - */ -extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); - -/** - * Initialize an SDL_AudioCVT structure for conversion. - * - * Before an SDL_AudioCVT structure can be used to convert audio data it must - * be initialized with source and destination information. - * - * This function will zero out every field of the SDL_AudioCVT, so it must be - * called before the application fills in the final buffer information. - * - * Once this function has returned successfully, and reported that a - * conversion is necessary, the application fills in the rest of the fields in - * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate, - * and then can call SDL_ConvertAudio() to complete the conversion. - * - * \param cvt an SDL_AudioCVT structure filled in with audio conversion - * information. - * \param src_format the source format of the audio data; for more info see - * SDL_AudioFormat. - * \param src_channels the number of channels in the source. - * \param src_rate the frequency (sample-frames-per-second) of the source. - * \param dst_format the destination format of the audio data; for more info - * see SDL_AudioFormat. - * \param dst_channels the number of channels in the destination. - * \param dst_rate the frequency (sample-frames-per-second) of the - * destination. - * \returns 1 if the audio filter is prepared, 0 if no conversion is needed, - * or a negative error code on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ConvertAudio - */ -extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, - SDL_AudioFormat src_format, - Uint8 src_channels, - int src_rate, - SDL_AudioFormat dst_format, - Uint8 dst_channels, - int dst_rate); - -/** - * Convert audio data to a desired audio format. - * - * This function does the actual audio data conversion, after the application - * has called SDL_BuildAudioCVT() to prepare the conversion information and - * then filled in the buffer details. - * - * Once the application has initialized the `cvt` structure using - * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio - * data in the source format, this function will convert the buffer, in-place, - * to the desired format. - * - * The data conversion may go through several passes; any given pass may - * possibly temporarily increase the size of the data. For example, SDL might - * expand 16-bit data to 32 bits before resampling to a lower frequency, - * shrinking the data size after having grown it briefly. Since the supplied - * buffer will be both the source and destination, converting as necessary - * in-place, the application must allocate a buffer that will fully contain - * the data during its largest conversion pass. After SDL_BuildAudioCVT() - * returns, the application should set the `cvt->len` field to the size, in - * bytes, of the source data, and allocate a buffer that is `cvt->len * - * cvt->len_mult` bytes long for the `buf` field. - * - * The source data should be copied into this buffer before the call to - * SDL_ConvertAudio(). Upon successful return, this buffer will contain the - * converted audio, and `cvt->len_cvt` will be the size of the converted data, - * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once - * this function returns. - * - * \param cvt an SDL_AudioCVT structure that was previously set up by - * SDL_BuildAudioCVT(). - * \returns 0 if the conversion was completed successfully or a negative error - * code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BuildAudioCVT - */ -extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); - -/* SDL_AudioStream is a new audio conversion interface. - The benefits vs SDL_AudioCVT: - - it can handle resampling data in chunks without generating - artifacts, when it doesn't have the complete buffer available. - - it can handle incoming data in any variable size. - - You push data as you have it, and pull it when you need it - */ -/* this is opaque to the outside world. */ -struct _SDL_AudioStream; -typedef struct _SDL_AudioStream SDL_AudioStream; - -/** - * Create a new audio stream. - * - * \param src_format The format of the source audio. - * \param src_channels The number of channels of the source audio. - * \param src_rate The sampling rate of the source audio. - * \param dst_format The format of the desired audio output. - * \param dst_channels The number of channels of the desired audio output. - * \param dst_rate The sampling rate of the desired audio output. - * \returns 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, - const Uint8 src_channels, - const int src_rate, - const SDL_AudioFormat dst_format, - const Uint8 dst_channels, - const int dst_rate); - -/** - * Add data to be converted/resampled to the stream. - * - * \param stream The stream the audio data is being added to. - * \param buf A pointer to the audio data to add. - * \param len The number of bytes to write to the stream. - * \returns 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); - -/** - * Get converted/resampled data from the stream - * - * \param stream The stream the audio is being requested from. - * \param buf A buffer to fill with audio data. - * \param len The maximum number of bytes to fill. - * \returns the number of bytes read from the stream, or -1 on error. - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len); - -/** - * Get the number of converted/resampled bytes available. - * - * The stream may be buffering data behind the scenes until it has enough to - * resample correctly, so this number might be lower than what you expect, or - * even be zero. Add more data or flush the stream if you need the data now. - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream); - -/** - * Tell the stream that you're done sending data, and anything being buffered - * should be converted/resampled and made available immediately. - * - * It is legal to add more data to a stream after flushing, but there will be - * audio gaps in the output. Generally this is intended to signal the end of - * input, so the complete output becomes available. - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamClear - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); - -/** - * Clear any pending data in the stream without converting it - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_FreeAudioStream - */ -extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); - -/** - * Free an audio stream - * - * \since This function is available since SDL 2.0.7. - * - * \sa SDL_NewAudioStream - * \sa SDL_AudioStreamPut - * \sa SDL_AudioStreamGet - * \sa SDL_AudioStreamAvailable - * \sa SDL_AudioStreamFlush - * \sa SDL_AudioStreamClear - */ -extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); - -/** - * Maximum volume allowed in calls to SDL_MixAudio and SDL_MixAudioFormat. - */ -#define SDL_MIX_MAXVOLUME 128 - -/** - * This function is a legacy means of mixing audio. - * - * This function is equivalent to calling... - * - * ```c - * SDL_MixAudioFormat(dst, src, format, len, volume); - * ``` - * - * ...where `format` is the obtained format of the audio device from the - * legacy SDL_OpenAudio() function. - * - * \param dst the destination for the mixed audio. - * \param src the source audio buffer to be mixed. - * \param len the length of the audio buffer in bytes. - * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME - * for full audio volume. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MixAudioFormat - */ -extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, - Uint32 len, int volume); - -/** - * Mix audio data in a specified format. - * - * This takes an audio buffer `src` of `len` bytes of `format` data and mixes - * it into `dst`, performing addition, volume adjustment, and overflow - * clipping. The buffer pointed to by `dst` must also be `len` bytes of - * `format` data. - * - * This is provided for convenience -- you can mix your own audio data. - * - * Do not use this function for mixing together more than two streams of - * sample data. The output from repeated application of this function may be - * distorted by clipping, because there is no accumulator with greater range - * than the input (not to mention this being an inefficient way of doing it). - * - * It is a common misconception that this function is required to write audio - * data to an output stream in an audio callback. While you can do that, - * SDL_MixAudioFormat() is really only needed when you're mixing a single - * audio stream with a volume adjustment. - * - * \param dst the destination for the mixed audio. - * \param src the source audio buffer to be mixed. - * \param format the SDL_AudioFormat structure representing the desired audio - * format. - * \param len the length of the audio buffer in bytes. - * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME - * for full audio volume. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, - const Uint8 * src, - SDL_AudioFormat format, - Uint32 len, int volume); - -/** - * Queue more audio on non-callback devices. - * - * If you are looking to retrieve queued audio from a non-callback capture - * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return - * -1 to signify an error if you use it with capture devices. - * - * SDL offers two ways to feed audio to the device: you can either supply a - * callback that SDL triggers with some frequency to obtain more audio (pull - * method), or you can supply no callback, and then SDL will expect you to - * supply data at regular intervals (push method) with this function. - * - * There are no limits on the amount of data you can queue, short of - * exhaustion of address space. Queued data will drain to the device as - * necessary without further intervention from you. If the device needs audio - * but there is not enough queued, it will play silence to make up the - * difference. This means you will have skips in your audio playback if you - * aren't routinely queueing sufficient data. - * - * This function copies the supplied data, so you are safe to free it when the - * function returns. This function is thread-safe, but queueing to the same - * device from two threads at once does not promise which buffer will be - * queued first. - * - * You may not queue audio on a device that is using an application-supplied - * callback; doing so returns an error. You have to use the audio callback or - * queue audio with this function, but not both. - * - * You should not call SDL_LockAudio() on the device before queueing; SDL - * handles locking internally for this function. - * - * Note that SDL2 does not support planar audio. You will need to resample - * from planar audio formats into a non-planar one (see SDL_AudioFormat) - * before queuing audio. - * - * \param dev the device ID to which we will queue audio. - * \param data the data to queue to the device for later playback. - * \param len the number of bytes (not samples!) to which `data` points. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_ClearQueuedAudio - * \sa SDL_GetQueuedAudioSize - */ -extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len); - -/** - * Dequeue more audio on non-callback devices. - * - * If you are looking to queue audio for output on a non-callback playback - * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always - * return 0 if you use it with playback devices. - * - * SDL offers two ways to retrieve audio from a capture device: you can either - * supply a callback that SDL triggers with some frequency as the device - * records more audio data, (push method), or you can supply no callback, and - * then SDL will expect you to retrieve data at regular intervals (pull - * method) with this function. - * - * There are no limits on the amount of data you can queue, short of - * exhaustion of address space. Data from the device will keep queuing as - * necessary without further intervention from you. This means you will - * eventually run out of memory if you aren't routinely dequeueing data. - * - * Capture devices will not queue data when paused; if you are expecting to - * not need captured audio for some length of time, use SDL_PauseAudioDevice() - * to stop the capture device from queueing more data. This can be useful - * during, say, level loading times. When unpaused, capture devices will start - * queueing data from that point, having flushed any capturable data available - * while paused. - * - * This function is thread-safe, but dequeueing from the same device from two - * threads at once does not promise which thread will dequeue data first. - * - * You may not dequeue audio from a device that is using an - * application-supplied callback; doing so returns an error. You have to use - * the audio callback, or dequeue audio with this function, but not both. - * - * You should not call SDL_LockAudio() on the device before dequeueing; SDL - * handles locking internally for this function. - * - * \param dev the device ID from which we will dequeue audio. - * \param data a pointer into where audio data should be copied. - * \param len the number of bytes (not samples!) to which (data) points. - * \returns the number of bytes dequeued, which could be less than requested; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_ClearQueuedAudio - * \sa SDL_GetQueuedAudioSize - */ -extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len); - -/** - * Get the number of bytes of still-queued audio. - * - * For playback devices: this is the number of bytes that have been queued for - * playback with SDL_QueueAudio(), but have not yet been sent to the hardware. - * - * Once we've sent it to the hardware, this function can not decide the exact - * byte boundary of what has been played. It's possible that we just gave the - * hardware several kilobytes right before you called this function, but it - * hasn't played any of it yet, or maybe half of it, etc. - * - * For capture devices, this is the number of bytes that have been captured by - * the device and are waiting for you to dequeue. This number may grow at any - * time, so this only informs of the lower-bound of available data. - * - * You may not queue or dequeue audio on a device that is using an - * application-supplied callback; calling this function on such a device - * always returns 0. You have to use the audio callback or queue audio, but - * not both. - * - * You should not call SDL_LockAudio() on the device before querying; SDL - * handles locking internally for this function. - * - * \param dev the device ID of which we will query queued audio size. - * \returns the number of bytes (not samples!) of queued audio. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_ClearQueuedAudio - * \sa SDL_QueueAudio - * \sa SDL_DequeueAudio - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); - -/** - * Drop any queued audio data waiting to be sent to the hardware. - * - * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For - * output devices, the hardware will start playing silence if more audio isn't - * queued. For capture devices, the hardware will start filling the empty - * queue with new data if the capture device isn't paused. - * - * This will not prevent playback of queued audio that's already been sent to - * the hardware, as we can not undo that, so expect there to be some fraction - * of a second of audio that might still be heard. This can be useful if you - * want to, say, drop any pending music or any unprocessed microphone input - * during a level change in your game. - * - * You may not queue or dequeue audio on a device that is using an - * application-supplied callback; calling this function on such a device - * always returns 0. You have to use the audio callback or queue audio, but - * not both. - * - * You should not call SDL_LockAudio() on the device before clearing the - * queue; SDL handles locking internally for this function. - * - * This function always succeeds and thus returns void. - * - * \param dev the device ID of which to clear the audio queue. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_GetQueuedAudioSize - * \sa SDL_QueueAudio - * \sa SDL_DequeueAudio - */ -extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev); - - -/** - * \name Audio lock functions - * - * The lock manipulated by these functions protects the callback function. - * During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that - * the callback function is not running. Do not call these from the callback - * function or you will cause deadlock. - */ -/* @{ */ - -/** - * This function is a legacy means of locking the audio device. - * - * New programs might want to use SDL_LockAudioDevice() instead. This function - * is equivalent to calling... - * - * ```c - * SDL_LockAudioDevice(1); - * ``` - * - * ...and is only useful if you used the legacy SDL_OpenAudio() function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockAudioDevice - * \sa SDL_UnlockAudio - * \sa SDL_UnlockAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_LockAudio(void); - -/** - * Use this function to lock out the audio callback function for a specified - * device. - * - * The lock manipulated by these functions protects the audio callback - * function specified in SDL_OpenAudioDevice(). During a - * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed - * that the callback function for that device is not running, even if the - * device is not paused. While a device is locked, any other unpaused, - * unlocked devices may still run their callbacks. - * - * Calling this function from inside your audio callback is unnecessary. SDL - * obtains this lock before calling your function, and releases it when the - * function returns. - * - * You should not hold the lock longer than absolutely necessary. If you hold - * it too long, you'll experience dropouts in your audio playback. Ideally, - * your application locks the device, sets a few variables and unlocks again. - * Do not do heavy work while holding the lock for a device. - * - * It is safe to lock the audio device multiple times, as long as you unlock - * it an equivalent number of times. The callback will not run until the - * device has been unlocked completely in this way. If your application fails - * to unlock the device appropriately, your callback will never run, you might - * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably - * deadlock. - * - * Internally, the audio device lock is a mutex; if you lock from two threads - * at once, not only will you block the audio callback, you'll block the other - * thread. - * - * \param dev the ID of the device to be locked. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_UnlockAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev); - -/** - * This function is a legacy means of unlocking the audio device. - * - * New programs might want to use SDL_UnlockAudioDevice() instead. This - * function is equivalent to calling... - * - * ```c - * SDL_UnlockAudioDevice(1); - * ``` - * - * ...and is only useful if you used the legacy SDL_OpenAudio() function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockAudio - * \sa SDL_UnlockAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); - -/** - * Use this function to unlock the audio callback function for a specified - * device. - * - * This function should be paired with a previous SDL_LockAudioDevice() call. - * - * \param dev the ID of the device to be unlocked. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev); -/* @} *//* Audio lock functions */ - -/** - * This function is a legacy means of closing the audio device. - * - * This function is equivalent to calling... - * - * ```c - * SDL_CloseAudioDevice(1); - * ``` - * - * ...and is only useful if you used the legacy SDL_OpenAudio() function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_OpenAudio - */ -extern DECLSPEC void SDLCALL SDL_CloseAudio(void); - -/** - * Use this function to shut down audio processing and close the audio device. - * - * The application should close open audio devices once they are no longer - * needed. Calling this function will wait until the device's audio callback - * is not running, release the audio hardware and then clean up internal - * state. No further audio will play from this device once this function - * returns. - * - * This function may block briefly while pending audio data is played by the - * hardware, so that applications don't drop the last buffer of data they - * supplied. - * - * The device ID is invalid as soon as the device is closed, and is eligible - * for reuse in a new SDL_OpenAudioDevice() call immediately. - * - * \param dev an audio device previously opened with SDL_OpenAudioDevice(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_OpenAudioDevice - */ -extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_audio_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_clipboard.h b/code/thirdparty/SDL2-2.32.8/include/SDL_clipboard.h deleted file mode 100644 index 2ae16a1d05..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_clipboard.h +++ /dev/null @@ -1,141 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryClipboard - * - * Include file for SDL clipboard handling - */ - -#ifndef SDL_clipboard_h_ -#define SDL_clipboard_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* Function prototypes */ - -/** - * Put UTF-8 text into the clipboard. - * - * \param text the text to store in the clipboard. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetClipboardText - * \sa SDL_HasClipboardText - */ -extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text); - -/** - * Get UTF-8 text from the clipboard, which must be freed with SDL_free(). - * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. - * - * \returns the clipboard text on success or an empty string on failure; call - * SDL_GetError() for more information. Caller must call SDL_free() - * on the returned pointer when done with it (even if there was an - * error). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasClipboardText - * \sa SDL_SetClipboardText - */ -extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void); - -/** - * Query whether the clipboard exists and contains a non-empty text string. - * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetClipboardText - * \sa SDL_SetClipboardText - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); - -/** - * Put UTF-8 text into the primary selection. - * - * \param text the text to store in the primary selection. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_GetPrimarySelectionText - * \sa SDL_HasPrimarySelectionText - */ -extern DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text); - -/** - * Get UTF-8 text from the primary selection, which must be freed with - * SDL_free(). - * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. - * - * \returns the primary selection text on success or an empty string on - * failure; call SDL_GetError() for more information. Caller must - * call SDL_free() on the returned pointer when done with it (even if - * there was an error). - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_HasPrimarySelectionText - * \sa SDL_SetPrimarySelectionText - */ -extern DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); - -/** - * Query whether the primary selection exists and contains a non-empty text - * string. - * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_GetPrimarySelectionText - * \sa SDL_SetPrimarySelectionText - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_clipboard_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_android.h b/code/thirdparty/SDL2-2.32.8/include/SDL_config_android.h deleted file mode 100644 index 0609995e97..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_android.h +++ /dev/null @@ -1,194 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_config_android_h_ -#define SDL_config_android_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/** - * \file SDL_config_android.h - * - * This is a configuration that can be used to build SDL for Android - */ - -#include - -#define HAVE_GCC_ATOMICS 1 - -#define STDC_HEADERS 1 -#define HAVE_ALLOCA_H 1 -#define HAVE_CTYPE_H 1 -#define HAVE_INTTYPES_H 1 -#define HAVE_LIMITS_H 1 -#define HAVE_MATH_H 1 -#define HAVE_SIGNAL_H 1 -#define HAVE_STDINT_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STRING_H 1 -#define HAVE_SYS_TYPES_H 1 - -/* C library functions */ -#define HAVE_DLOPEN 1 -#define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -#define HAVE_GETENV 1 -#define HAVE_SETENV 1 -#define HAVE_PUTENV 1 -#define HAVE_SETENV 1 -#define HAVE_UNSETENV 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#define HAVE_ABS 1 -#define HAVE_BCOPY 1 -#define HAVE_MEMSET 1 -#define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 -#define HAVE_MEMCMP 1 -#define HAVE_STRLEN 1 -#define HAVE_STRLCPY 1 -#define HAVE_STRLCAT 1 -#define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 -#define HAVE_STRSTR 1 -#define HAVE_STRTOK_R 1 -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_STRTOD 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 -#define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_STRCASESTR 1 -#define HAVE_VSSCANF 1 -#define HAVE_VSNPRINTF 1 -#define HAVE_ACOS 1 -#define HAVE_ACOSF 1 -#define HAVE_ASIN 1 -#define HAVE_ASINF 1 -#define HAVE_ATAN 1 -#define HAVE_ATANF 1 -#define HAVE_ATAN2 1 -#define HAVE_ATAN2F 1 -#define HAVE_CEIL 1 -#define HAVE_CEILF 1 -#define HAVE_COPYSIGN 1 -#define HAVE_COPYSIGNF 1 -#define HAVE_COS 1 -#define HAVE_COSF 1 -#define HAVE_EXP 1 -#define HAVE_EXPF 1 -#define HAVE_FABS 1 -#define HAVE_FABSF 1 -#define HAVE_FLOOR 1 -#define HAVE_FLOORF 1 -#define HAVE_FMOD 1 -#define HAVE_FMODF 1 -#define HAVE_LOG 1 -#define HAVE_LOGF 1 -#define HAVE_LOG10 1 -#define HAVE_LOG10F 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_POW 1 -#define HAVE_POWF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE_SCALBN 1 -#define HAVE_SCALBNF 1 -#define HAVE_SIN 1 -#define HAVE_SINF 1 -#define HAVE_SQRT 1 -#define HAVE_SQRTF 1 -#define HAVE_TAN 1 -#define HAVE_TANF 1 -#define HAVE_TRUNC 1 -#define HAVE_TRUNCF 1 -#define HAVE_SIGACTION 1 -#define HAVE_SETJMP 1 -#define HAVE_NANOSLEEP 1 -#define HAVE_SYSCONF 1 -#define HAVE_CLOCK_GETTIME 1 - -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -/* Enable various audio drivers */ -#define SDL_AUDIO_DRIVER_ANDROID 1 -#define SDL_AUDIO_DRIVER_OPENSLES 1 -#define SDL_AUDIO_DRIVER_AAUDIO 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 - -/* Enable various input drivers */ -#define SDL_JOYSTICK_ANDROID 1 -#define SDL_JOYSTICK_HIDAPI 1 -#define SDL_JOYSTICK_VIRTUAL 1 -#define SDL_HAPTIC_ANDROID 1 - -/* Enable sensor driver */ -#define SDL_SENSOR_ANDROID 1 - -/* Enable various shared object loading systems */ -#define SDL_LOADSO_DLOPEN 1 - -/* Enable various threading systems */ -#define SDL_THREAD_PTHREAD 1 -#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 - -/* Enable various timer systems */ -#define SDL_TIMER_UNIX 1 - -/* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_ANDROID 1 - -/* Enable OpenGL ES */ -#define SDL_VIDEO_OPENGL_ES 1 -#define SDL_VIDEO_OPENGL_ES2 1 -#define SDL_VIDEO_OPENGL_EGL 1 -#define SDL_VIDEO_RENDER_OGL_ES 1 -#define SDL_VIDEO_RENDER_OGL_ES2 1 - -/* Enable Vulkan support */ -/* Android does not support Vulkan in native code using the "armeabi" ABI. */ -#if defined(__ARM_ARCH) && __ARM_ARCH < 7 -#define SDL_VIDEO_VULKAN 0 -#else -#define SDL_VIDEO_VULKAN 1 -#endif - -/* Enable system power support */ -#define SDL_POWER_ANDROID 1 - -/* Enable the filesystem driver */ -#define SDL_FILESYSTEM_ANDROID 1 - -#endif /* SDL_config_android_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_ngage.h b/code/thirdparty/SDL2-2.32.8/include/SDL_config_ngage.h deleted file mode 100644 index b6042cd19e..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_ngage.h +++ /dev/null @@ -1,89 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_config_ngage_h_ -#define SDL_config_ngage_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -typedef signed char int8_t; -typedef unsigned char uint8_t; -typedef signed short int16_t; -typedef unsigned short uint16_t; -typedef signed int int32_t; -typedef unsigned int uint32_t; -typedef signed long long int64_t; -typedef unsigned long long uint64_t; -typedef unsigned long uintptr_t; - -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STDLIB_H 1 -#define HAVE_MATH_H 1 -#define HAVE_CEIL 1 -#define HAVE_COPYSIGN 1 -#define HAVE_COS 1 -#define HAVE_EXP 1 -#define HAVE_FABS 1 -#define HAVE_FLOOR 1 -#define HAVE_LOG 1 -#define HAVE_LOG10 1 -#define HAVE_SCALBN 1 -#define HAVE_SIN 1 -#define HAVE_SQRT 1 -#define HAVE_TAN 1 -#define HAVE_MALLOC 1 -#define SDL_MAIN_NEEDED 1 -#define LACKS_SYS_MMAN_H 1 - -/* Enable the N-Gage thread support (src/thread/ngage/\*.c) */ -#define SDL_THREAD_NGAGE 1 - -/* Enable the N-Gage timer support (src/timer/ngage/\*.c) */ -#define SDL_TIMER_NGAGE 1 - -/* Enable the N-Gage video driver (src/video/ngage/\*.c) */ -#define SDL_VIDEO_DRIVER_NGAGE 1 - -/* Enable the dummy audio driver (src/audio/dummy/\*.c) */ -#define SDL_AUDIO_DRIVER_DUMMY 1 - -/* Enable the stub joystick driver (src/joystick/dummy/\*.c) */ -#define SDL_JOYSTICK_DISABLED 1 - -/* Enable the stub haptic driver (src/haptic/dummy/\*.c) */ -#define SDL_HAPTIC_DISABLED 1 - -/* Enable the stub HIDAPI */ -#define SDL_HIDAPI_DISABLED 1 - -/* Enable the stub sensor driver (src/sensor/dummy/\*.c) */ -#define SDL_SENSOR_DISABLED 1 - -/* Enable the stub shared object loader (src/loadso/dummy/\*.c) */ -#define SDL_LOADSO_DISABLED 1 - -/* Enable the dummy filesystem driver (src/filesystem/dummy/\*.c) */ -#define SDL_FILESYSTEM_DUMMY 1 - -#endif /* SDL_config_ngage_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_os2.h b/code/thirdparty/SDL2-2.32.8/include/SDL_config_os2.h deleted file mode 100644 index 22fafb1f0e..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_os2.h +++ /dev/null @@ -1,204 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_config_os2_h_ -#define SDL_config_os2_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -#define SIZEOF_VOIDP 4 - -#define SDL_AUDIO_DRIVER_DUMMY 1 -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_OS2 1 - -#define SDL_POWER_DISABLED 1 -#define SDL_HAPTIC_DISABLED 1 - -#define SDL_SENSOR_DUMMY 1 -#define SDL_VIDEO_DRIVER_DUMMY 1 -#define SDL_VIDEO_DRIVER_OS2 1 -#define SDL_JOYSTICK_OS2 1 -#ifndef HAVE_LIBUSB_H /* see Makefile */ -#define SDL_HIDAPI_DISABLED 1 -/*#undef SDL_JOYSTICK_HIDAPI */ -#else -#define SDL_JOYSTICK_HIDAPI 1 -#define HAVE_LIBUSB 1 -/* dynamically loaded libusb-1.0 dll: */ -#define SDL_LIBUSB_DYNAMIC "usb100.dll" -#endif -#define SDL_JOYSTICK_VIRTUAL 1 - -/* Enable OpenGL support */ -/* #undef SDL_VIDEO_OPENGL */ - -#define SDL_THREAD_OS2 1 -#define SDL_LOADSO_OS2 1 -#define SDL_TIMER_OS2 1 -#define SDL_FILESYSTEM_OS2 1 - -/* use libsamplerate for audio rate conversion. */ -/*#define HAVE_LIBSAMPLERATE_H 1 */ - -/* Enable dynamic libsamplerate support */ -#define SDL_LIBSAMPLERATE_DYNAMIC "SAMPRATE.DLL" - -#define HAVE_LIBC 1 - -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#define HAVE_STDINT_H 1 - -#define HAVE_SYS_TYPES_H 1 -#define HAVE_STDIO_H 1 -#define STDC_HEADERS 1 -#define HAVE_STDLIB_H 1 -#define HAVE_MALLOC_H 1 -#define HAVE_MEMORY_H 1 -#define HAVE_STRING_H 1 -#define HAVE_STRINGS_H 1 -#define HAVE_WCHAR_H 1 -#define HAVE_INTTYPES_H 1 -#define HAVE_LIMITS_H 1 -#define HAVE_CTYPE_H 1 -#define HAVE_MATH_H 1 -#define HAVE_FLOAT_H 1 -#define HAVE_SIGNAL_H 1 - -#if 0 /* see Makefile */ -#define HAVE_ICONV 1 -#define HAVE_ICONV_H 1 -#endif - -/* #undef HAVE_DLOPEN */ -#define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#if defined(__WATCOMC__) -#define HAVE__FSEEKI64 1 -#define HAVE__FTELLI64 1 -#endif -#define HAVE_ALLOCA 1 -#define HAVE_GETENV 1 -#define HAVE_SETENV 1 -#define HAVE_PUTENV 1 -/* OpenWatcom requires specific calling conventions for qsort and bsearch */ -#ifndef __WATCOMC__ -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#endif -#define HAVE_ABS 1 -#define HAVE_BCOPY 1 -#define HAVE_MEMSET 1 -#define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 -#define HAVE_MEMCMP 1 -#define HAVE_WCSCMP 1 -#define HAVE__WCSICMP 1 -#define HAVE__WCSNICMP 1 -#define HAVE_WCSLEN 1 -#define HAVE_WCSLCPY 1 -#define HAVE_WCSLCAT 1 -/* #undef HAVE_WCSDUP */ -#define HAVE__WCSDUP 1 -#define HAVE_WCSSTR 1 -#define HAVE_WCSCMP 1 -#define HAVE_WCSNCMP 1 -#define HAVE_STRLEN 1 -#define HAVE_STRLCPY 1 -#define HAVE_STRLCAT 1 -#define HAVE__STRREV 1 -#define HAVE__STRUPR 1 -#define HAVE__STRLWR 1 -/* #undef HAVE_INDEX */ -/* #undef HAVE_RINDEX */ -#define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 -#define HAVE_STRSTR 1 -/* #undef HAVE_STRTOK_R */ -#define HAVE_ITOA 1 -#define HAVE__LTOA 1 -#define HAVE__ULTOA 1 -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -#define HAVE__I64TOA 1 -#define HAVE__UI64TOA 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_STRTOD 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 -#define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE_STRICMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_SSCANF 1 -#define HAVE_VSSCANF 1 -#define HAVE_SNPRINTF 1 -#define HAVE_VSNPRINTF 1 -#define HAVE_SETJMP 1 -#define HAVE_ACOS 1 -/* #undef HAVE_ACOSF */ -#define HAVE_ASIN 1 -/* #undef HAVE_ASINF */ -#define HAVE_ATAN 1 -#define HAVE_ATAN2 1 -/* #undef HAVE_ATAN2F */ -#define HAVE_CEIL 1 -/* #undef HAVE_CEILF */ -/* #undef HAVE_COPYSIGN */ -/* #undef HAVE_COPYSIGNF */ -#define HAVE_COS 1 -/* #undef HAVE_COSF */ -#define HAVE_EXP 1 -/* #undef HAVE_EXPF */ -#define HAVE_FABS 1 -/* #undef HAVE_FABSF */ -#define HAVE_FLOOR 1 -/* #undef HAVE_FLOORF */ -#define HAVE_FMOD 1 -/* #undef HAVE_FMODF */ -#define HAVE_LOG 1 -/* #undef HAVE_LOGF */ -#define HAVE_LOG10 1 -/* #undef HAVE_LOG10F */ -#define HAVE_POW 1 -/* #undef HAVE_POWF */ -#define HAVE_SIN 1 -/* #undef HAVE_SINF */ -/* #undef HAVE_SCALBN */ -/* #undef HAVE_SCALBNF */ -#define HAVE_SQRT 1 -/* #undef HAVE_SQRTF */ -#define HAVE_TAN 1 -/* #undef HAVE_TANF */ -/* #undef HAVE_TRUNC */ -/* #undef HAVE_TRUNCF */ -/* #undef HAVE_LROUND */ -/* #undef HAVE_LROUNDF */ -/* #undef HAVE_ROUND */ -/* #undef HAVE_ROUNDF */ - -#endif /* SDL_config_os2_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_pandora.h b/code/thirdparty/SDL2-2.32.8/include/SDL_config_pandora.h deleted file mode 100644 index 96375c1e05..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_pandora.h +++ /dev/null @@ -1,141 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_config_pandora_h_ -#define SDL_config_pandora_h_ -#define SDL_config_h_ - -/* This is a set of defines to configure the SDL features */ - -/* General platform specific identifiers */ -#include "SDL_platform.h" - -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -#define SDL_BYTEORDER 1234 - -#define STDC_HEADERS 1 -#define HAVE_ALLOCA_H 1 -#define HAVE_CTYPE_H 1 -#define HAVE_ICONV_H 1 -#define HAVE_INTTYPES_H 1 -#define HAVE_LIMITS_H 1 -#define HAVE_MALLOC_H 1 -#define HAVE_MATH_H 1 -#define HAVE_MEMORY_H 1 -#define HAVE_SIGNAL_H 1 -#define HAVE_STDARG_H 1 -#define HAVE_STDINT_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STDLIB_H 1 -#define HAVE_STRINGS_H 1 -#define HAVE_STRING_H 1 -#define HAVE_SYS_TYPES_H 1 - -#define HAVE_DLOPEN 1 -#define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -#define HAVE_GETENV 1 -#define HAVE_SETENV 1 -#define HAVE_PUTENV 1 -#define HAVE_UNSETENV 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#define HAVE_ABS 1 -#define HAVE_BCOPY 1 -#define HAVE_MEMSET 1 -#define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 -#define HAVE_STRLEN 1 -#define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 -#define HAVE_STRSTR 1 -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 -#define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_VSSCANF 1 -#define HAVE_VSNPRINTF 1 -#define HAVE_M_PI 1 -#define HAVE_CEIL 1 -#define HAVE_COPYSIGN 1 -#define HAVE_COS 1 -#define HAVE_COSF 1 -#define HAVE_EXP 1 -#define HAVE_FABS 1 -#define HAVE_FLOOR 1 -#define HAVE_LOG 1 -#define HAVE_LOG10 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE_SCALBN 1 -#define HAVE_SIN 1 -#define HAVE_SINF 1 -#define HAVE_SQRT 1 -#define HAVE_SQRTF 1 -#define HAVE_TAN 1 -#define HAVE_TANF 1 -#define HAVE_TRUNC 1 -#define HAVE_TRUNCF 1 -#define HAVE_SIGACTION 1 -#define HAVE_SETJMP 1 -#define HAVE_NANOSLEEP 1 - -#define SDL_AUDIO_DRIVER_DUMMY 1 -#define SDL_AUDIO_DRIVER_OSS 1 - -#define SDL_INPUT_LINUXEV 1 -#define SDL_JOYSTICK_LINUX 1 -#define SDL_JOYSTICK_VIRTUAL 1 -#define SDL_HAPTIC_LINUX 1 - -#define SDL_SENSOR_DUMMY 1 - -#define SDL_LOADSO_DLOPEN 1 - -#define SDL_THREAD_PTHREAD 1 -#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX_NP 1 - -#define SDL_TIMER_UNIX 1 -#define SDL_FILESYSTEM_UNIX 1 - -#define SDL_VIDEO_DRIVER_DUMMY 1 -#define SDL_VIDEO_DRIVER_X11 1 -#define SDL_VIDEO_DRIVER_PANDORA 1 -#define SDL_VIDEO_RENDER_OGL_ES 1 -#define SDL_VIDEO_OPENGL_ES 1 - -#endif /* SDL_config_pandora_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_winrt.h b/code/thirdparty/SDL2-2.32.8/include/SDL_config_winrt.h deleted file mode 100644 index 8fe0b66dbf..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_winrt.h +++ /dev/null @@ -1,220 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_config_winrt_h_ -#define SDL_config_winrt_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* Make sure the Windows SDK's NTDDI_VERSION macro gets defined. This is used - by SDL to determine which version of the Windows SDK is being used. -*/ -#include - -/* Define possibly-undefined NTDDI values (used when compiling SDL against - older versions of the Windows SDK. -*/ -#ifndef NTDDI_WINBLUE -#define NTDDI_WINBLUE 0x06030000 -#endif -#ifndef NTDDI_WIN10 -#define NTDDI_WIN10 0x0A000000 -#endif - -/* This is a set of defines to configure the SDL features */ - -#ifdef _WIN64 -# define SIZEOF_VOIDP 8 -#else -# define SIZEOF_VOIDP 4 -#endif - -#ifdef __clang__ -# define HAVE_GCC_ATOMICS 1 -#endif - -/* Useful headers */ -#define HAVE_DXGI_H 1 -#if !SDL_WINAPI_FAMILY_PHONE -#define HAVE_XINPUT_H 1 -#endif - -#define HAVE_MMDEVICEAPI_H 1 -#define HAVE_AUDIOCLIENT_H 1 -#define HAVE_TPCSHRD_H 1 - -#define HAVE_LIBC 1 -#define STDC_HEADERS 1 -#define HAVE_CTYPE_H 1 -#define HAVE_FLOAT_H 1 -#define HAVE_LIMITS_H 1 -#define HAVE_MATH_H 1 -#define HAVE_SIGNAL_H 1 -#define HAVE_STDINT_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STRING_H 1 - -/* C library functions */ -#define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#define HAVE_ABS 1 -#define HAVE_MEMSET 1 -#define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 -#define HAVE_MEMCMP 1 -#define HAVE_STRLEN 1 -#define HAVE__STRREV 1 -#define HAVE__STRUPR 1 -#define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 -#define HAVE_STRSTR 1 -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -/* #undef HAVE_STRTOLL */ -/* #undef HAVE_STRTOULL */ -#define HAVE_STRTOD 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 -#define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE__STRICMP 1 -#define HAVE__STRNICMP 1 -#define HAVE_VSNPRINTF 1 -/* TODO, WinRT: consider using ??_s versions of the following */ -/* #undef HAVE__STRLWR */ -/* #undef HAVE_ITOA */ -/* #undef HAVE__LTOA */ -/* #undef HAVE__ULTOA */ -/* #undef HAVE_SSCANF */ -#define HAVE_M_PI 1 -#define HAVE_ACOS 1 -#define HAVE_ACOSF 1 -#define HAVE_ASIN 1 -#define HAVE_ASINF 1 -#define HAVE_ATAN 1 -#define HAVE_ATANF 1 -#define HAVE_ATAN2 1 -#define HAVE_ATAN2F 1 -#define HAVE_CEIL 1 -#define HAVE_CEILF 1 -#define HAVE__COPYSIGN 1 -#define HAVE_COS 1 -#define HAVE_COSF 1 -#define HAVE_EXP 1 -#define HAVE_EXPF 1 -#define HAVE_FABS 1 -#define HAVE_FABSF 1 -#define HAVE_FLOOR 1 -#define HAVE_FLOORF 1 -#define HAVE_FMOD 1 -#define HAVE_FMODF 1 -#define HAVE_LOG 1 -#define HAVE_LOGF 1 -#define HAVE_LOG10 1 -#define HAVE_LOG10F 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_POW 1 -#define HAVE_POWF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE__SCALB 1 -#define HAVE_SIN 1 -#define HAVE_SINF 1 -#define HAVE_SQRT 1 -#define HAVE_SQRTF 1 -#define HAVE_TAN 1 -#define HAVE_TANF 1 -#define HAVE_TRUNC 1 -#define HAVE_TRUNCF 1 -#define HAVE__FSEEKI64 1 - -#define HAVE_ROAPI_H 1 - -/* Enable various audio drivers */ -#define SDL_AUDIO_DRIVER_WASAPI 1 -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 - -/* Enable various input drivers */ -#if SDL_WINAPI_FAMILY_PHONE -#define SDL_JOYSTICK_DISABLED 1 -#define SDL_HAPTIC_DISABLED 1 -#else -#define SDL_JOYSTICK_VIRTUAL 1 -#if (NTDDI_VERSION >= NTDDI_WIN10) -#define SDL_JOYSTICK_WGI 1 -#define SDL_HAPTIC_DISABLED 1 -#else -#define SDL_JOYSTICK_XINPUT 1 -#define SDL_HAPTIC_XINPUT 1 -#endif /* WIN10 */ -#endif - -/* WinRT doesn't have HIDAPI available */ -#define SDL_HIDAPI_DISABLED 1 - -/* Enable the dummy sensor driver */ -#define SDL_SENSOR_DUMMY 1 - -/* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 - -/* Enable various threading systems */ -#if (NTDDI_VERSION >= NTDDI_WINBLUE) -#define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 -#else -/* WinRT on Windows 8.0 and Windows Phone 8.0 don't support CreateThread() */ -#define SDL_THREAD_STDCPP 1 -#endif - -/* Enable various timer systems */ -#define SDL_TIMER_WINDOWS 1 - -/* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_WINRT 1 -#define SDL_VIDEO_DRIVER_DUMMY 1 - -/* Enable OpenGL ES 2.0 (via a modified ANGLE library) */ -#define SDL_VIDEO_OPENGL_ES2 1 -#define SDL_VIDEO_OPENGL_EGL 1 - -/* Enable appropriate renderer(s) */ -#define SDL_VIDEO_RENDER_D3D11 1 - -/* Disable D3D12 as it's not implemented for WinRT */ -/* #undef SDL_VIDEO_RENDER_D3D12 */ - -#ifdef SDL_VIDEO_OPENGL_ES2 -#define SDL_VIDEO_RENDER_OGL_ES2 1 -#endif - -/* Enable system power support */ -#define SDL_POWER_WINRT 1 - -#endif /* SDL_config_winrt_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_cpuinfo.h b/code/thirdparty/SDL2-2.32.8/include/SDL_cpuinfo.h deleted file mode 100644 index 696a03bf7b..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_cpuinfo.h +++ /dev/null @@ -1,603 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: CPUInfo */ - -/** - * # CategoryCPUInfo - * - * CPU feature detection for SDL. - * - * These functions are largely concerned with reporting if the system has - * access to various SIMD instruction sets, but also has other important info - * to share, such as number of logical CPU cores. - */ - -#ifndef SDL_cpuinfo_h_ -#define SDL_cpuinfo_h_ - -#include "SDL_stdinc.h" - -/* Need to do this here because intrin.h has C++ code in it */ -/* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ -#if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) -#ifdef __clang__ -/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version, - so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */ - -#ifndef __PRFCHWINTRIN_H -#define __PRFCHWINTRIN_H - -static __inline__ void __attribute__((__always_inline__, __nodebug__)) -_m_prefetch(void *__P) -{ - __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */); -} - -#endif /* __PRFCHWINTRIN_H */ -#endif /* __clang__ */ -#include -#ifndef _WIN64 -#ifndef __MMX__ -#define __MMX__ -#endif -/* -#ifndef __3dNOW__ -#define __3dNOW__ -#endif -*/ -#endif -#ifndef __SSE__ -#define __SSE__ -#endif -#ifndef __SSE2__ -#define __SSE2__ -#endif -#ifndef __SSE3__ -#define __SSE3__ -#endif -#elif defined(__MINGW64_VERSION_MAJOR) -#include -#if !defined(SDL_DISABLE_ARM_NEON_H) && defined(__ARM_NEON) -# include -#endif -#else -/* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC_H to have it included. */ -#if defined(HAVE_ALTIVEC_H) && defined(__ALTIVEC__) && !defined(__APPLE_ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC_H) -#include -#endif -#if !defined(SDL_DISABLE_ARM_NEON_H) -# if defined(__ARM_NEON) -# include -# elif defined(__WINDOWS__) || defined(__WINRT__) || defined(__GDK__) -/* Visual Studio doesn't define __ARM_ARCH, but _M_ARM (if set, always 7), and _M_ARM64 (if set, always 1). */ -# if defined(_M_ARM) -# include -# include -# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */ -# endif -# if defined (_M_ARM64) -# include -# include -# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */ -# define __ARM_ARCH 8 -# endif -# endif -#endif -#endif /* compiler version */ - -#if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H) -#include -#endif -#if defined(__loongarch_sx) && !defined(SDL_DISABLE_LSX_H) -#include -#define __LSX__ -#endif -#if defined(__loongarch_asx) && !defined(SDL_DISABLE_LASX_H) -#include -#define __LASX__ -#endif -#if defined(HAVE_IMMINTRIN_H) && !defined(SDL_DISABLE_IMMINTRIN_H) && \ - (defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86)) -#include -#else -#if defined(__MMX__) && !defined(SDL_DISABLE_MMINTRIN_H) -#include -#endif -#if defined(__SSE__) && !defined(SDL_DISABLE_XMMINTRIN_H) -#include -#endif -#if defined(__SSE2__) && !defined(SDL_DISABLE_EMMINTRIN_H) -#include -#endif -#if defined(__SSE3__) && !defined(SDL_DISABLE_PMMINTRIN_H) -#include -#endif -#endif /* HAVE_IMMINTRIN_H */ - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* This is a guess for the cacheline size used for padding. - * Most x86 processors have a 64 byte cache line. - * The 64-bit PowerPC processors have a 128 byte cache line. - * We'll use the larger value to be generally safe. - */ -#define SDL_CACHELINE_SIZE 128 - -/** - * Get the number of CPU cores available. - * - * \returns the total number of logical CPU cores. On CPUs that include - * technologies such as hyperthreading, the number of logical cores - * may be more than the number of physical cores. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_GetCPUCount(void); - -/** - * Determine the L1 cache line size of the CPU. - * - * This is useful for determining multi-threaded structure padding or SIMD - * prefetch sizes. - * - * \returns the L1 cache line size of the CPU, in bytes. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); - -/** - * Determine whether the CPU has the RDTSC instruction. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void); - -/** - * Determine whether the CPU has AltiVec features. - * - * This always returns false on CPUs that aren't using PowerPC instruction - * sets. - * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); - -/** - * Determine whether the CPU has MMX features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); - -/** - * Determine whether the CPU has 3DNow! features. - * - * This always returns false on CPUs that aren't using AMD instruction sets. - * - * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void); - -/** - * Determine whether the CPU has SSE features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); - -/** - * Determine whether the CPU has SSE2 features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); - -/** - * Determine whether the CPU has SSE3 features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); - -/** - * Determine whether the CPU has SSE4.1 features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); - -/** - * Determine whether the CPU has SSE4.2 features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); - -/** - * Determine whether the CPU has AVX features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX2 - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); - -/** - * Determine whether the CPU has AVX2 features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_Has3DNow - * \sa SDL_HasAltiVec - * \sa SDL_HasAVX - * \sa SDL_HasMMX - * \sa SDL_HasRDTSC - * \sa SDL_HasSSE - * \sa SDL_HasSSE2 - * \sa SDL_HasSSE3 - * \sa SDL_HasSSE41 - * \sa SDL_HasSSE42 - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); - -/** - * Determine whether the CPU has AVX-512F (foundation) features. - * - * This always returns false on CPUs that aren't using Intel instruction sets. - * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_HasAVX - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); - -/** - * Determine whether the CPU has ARM SIMD (ARMv6) features. - * - * This is different from ARM NEON, which is a different instruction set. - * - * This always returns false on CPUs that aren't using ARM instruction sets. - * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_HasNEON - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); - -/** - * Determine whether the CPU has NEON (ARM SIMD) features. - * - * This always returns false on CPUs that aren't using ARM instruction sets. - * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); - -/** - * Determine whether the CPU has LSX (LOONGARCH SIMD) features. - * - * This always returns false on CPUs that aren't using LOONGARCH instruction - * sets. - * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); - -/** - * Determine whether the CPU has LASX (LOONGARCH SIMD) features. - * - * This always returns false on CPUs that aren't using LOONGARCH instruction - * sets. - * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); - -/** - * Get the amount of RAM configured in the system. - * - * \returns the amount of RAM configured in the system in MiB. - * - * \since This function is available since SDL 2.0.1. - */ -extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void); - -/** - * Report the alignment this system needs for SIMD allocations. - * - * This will return the minimum number of bytes to which a pointer must be - * aligned to be compatible with SIMD instructions on the current machine. For - * example, if the machine supports SSE only, it will return 16, but if it - * supports AVX-512F, it'll return 64 (etc). This only reports values for - * instruction sets SDL knows about, so if your SDL build doesn't have - * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and - * not 64 for the AVX-512 instructions that exist but SDL doesn't know about. - * Plan accordingly. - * - * \returns the alignment in bytes needed for available, known SIMD - * instructions. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void); - -/** - * Allocate memory in a SIMD-friendly way. - * - * This will allocate a block of memory that is suitable for use with SIMD - * instructions. Specifically, it will be properly aligned and padded for the - * system's supported vector instructions. - * - * The memory returned will be padded such that it is safe to read or write an - * incomplete vector at the end of the memory block. This can be useful so you - * don't have to drop back to a scalar fallback at the end of your SIMD - * processing loop to deal with the final elements without overflowing the - * allocated buffer. - * - * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or - * delete[], etc. - * - * Note that SDL will only deal with SIMD instruction sets it is aware of; for - * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and - * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants - * 64. To be clear: if you can't decide to use an instruction set with an - * SDL_Has*() function, don't use that instruction set with memory allocated - * through here. - * - * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't - * out of memory, but you are not allowed to dereference it (because you only - * own zero bytes of that buffer). - * - * \param len The length, in bytes, of the block to allocate. The actual - * allocated block might be larger due to padding, etc. - * \returns a pointer to the newly-allocated block, NULL if out of memory. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_SIMDGetAlignment - * \sa SDL_SIMDRealloc - * \sa SDL_SIMDFree - */ -extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len); - -/** - * Reallocate memory obtained from SDL_SIMDAlloc - * - * It is not valid to use this function on a pointer from anything but - * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc, - * SDL_malloc, memalign, new[], etc. - * - * \param mem The pointer obtained from SDL_SIMDAlloc. This function also - * accepts NULL, at which point this function is the same as - * calling SDL_SIMDAlloc with a NULL pointer. - * \param len The length, in bytes, of the block to allocated. The actual - * allocated block might be larger due to padding, etc. Passing 0 - * will return a non-NULL pointer, assuming the system isn't out of - * memory. - * \returns a pointer to the newly-reallocated block, NULL if out of memory. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_SIMDGetAlignment - * \sa SDL_SIMDAlloc - * \sa SDL_SIMDFree - */ -extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len); - -/** - * Deallocate memory obtained from SDL_SIMDAlloc - * - * It is not valid to use this function on a pointer from anything but - * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from - * malloc, realloc, SDL_malloc, memalign, new[], etc. - * - * However, SDL_SIMDFree(NULL) is a legal no-op. - * - * The memory pointed to by `ptr` is no longer valid for access upon return, - * and may be returned to the system or reused by a future allocation. The - * pointer passed to this function is no longer safe to dereference once this - * function returns, and should be discarded. - * - * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to - * deallocate. NULL is a legal no-op. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_SIMDAlloc - * \sa SDL_SIMDRealloc - */ -extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_cpuinfo_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_endian.h b/code/thirdparty/SDL2-2.32.8/include/SDL_endian.h deleted file mode 100644 index 5be66eafb9..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_endian.h +++ /dev/null @@ -1,396 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryEndian - * - * Functions for reading and writing endian-specific values - */ - -#ifndef SDL_endian_h_ -#define SDL_endian_h_ - -#include "SDL_stdinc.h" - -#if defined(_MSC_VER) && (_MSC_VER >= 1400) -/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version, - so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */ -#ifdef __clang__ -#ifndef __PRFCHWINTRIN_H -#define __PRFCHWINTRIN_H -static __inline__ void __attribute__((__always_inline__, __nodebug__)) -_m_prefetch(void *__P) -{ - __builtin_prefetch(__P, 0, 3 /* _MM_HINT_T0 */); -} -#endif /* __PRFCHWINTRIN_H */ -#endif /* __clang__ */ - -#include -#endif - -/** - * \name The two types of endianness - */ -/* @{ */ -#define SDL_LIL_ENDIAN 1234 -#define SDL_BIG_ENDIAN 4321 -/* @} */ - -#ifndef SDL_BYTEORDER /* Not defined in SDL_config.h? */ -#ifdef __linux__ -#include -#define SDL_BYTEORDER __BYTE_ORDER -#elif defined(__sun) && defined(__SVR4) /* Solaris */ -#include -#if defined(_LITTLE_ENDIAN) -#define SDL_BYTEORDER SDL_LIL_ENDIAN -#elif defined(_BIG_ENDIAN) -#define SDL_BYTEORDER SDL_BIG_ENDIAN -#else -#error Unsupported endianness -#endif -#elif defined(__OpenBSD__) || defined(__DragonFly__) -#include -#define SDL_BYTEORDER BYTE_ORDER -#elif defined(__FreeBSD__) || defined(__NetBSD__) -#include -#define SDL_BYTEORDER BYTE_ORDER -/* predefs from newer gcc and clang versions: */ -#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__BYTE_ORDER__) -#if (__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__) -#define SDL_BYTEORDER SDL_LIL_ENDIAN -#elif (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__) -#define SDL_BYTEORDER SDL_BIG_ENDIAN -#else -#error Unsupported endianness -#endif /**/ -#else -#if defined(__hppa__) || \ - defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \ - (defined(__MIPS__) && defined(__MIPSEB__)) || \ - defined(__ppc__) || defined(__POWERPC__) || defined(__powerpc__) || defined(__PPC__) || \ - defined(__sparc__) || defined(__sparc) -#define SDL_BYTEORDER SDL_BIG_ENDIAN -#else -#define SDL_BYTEORDER SDL_LIL_ENDIAN -#endif -#endif /* __linux__ */ -#endif /* !SDL_BYTEORDER */ - -#ifndef SDL_FLOATWORDORDER /* Not defined in SDL_config.h? */ -/* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) -#if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) -#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN -#elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) -#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN -#else -#error Unsupported endianness -#endif /**/ -#elif defined(__MAVERICK__) -/* For Maverick, float words are always little-endian. */ -#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN -#elif (defined(__arm__) || defined(__thumb__)) && !defined(__VFP_FP__) && !defined(__ARM_EABI__) -/* For FPA, float words are always big-endian. */ -#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN -#else -/* By default, assume that floats words follow the memory system mode. */ -#define SDL_FLOATWORDORDER SDL_BYTEORDER -#endif /* __FLOAT_WORD_ORDER__ */ -#endif /* !SDL_FLOATWORDORDER */ - - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \file SDL_endian.h - */ - -/* various modern compilers may have builtin swap */ -#if defined(__GNUC__) || defined(__clang__) -# define HAS_BUILTIN_BSWAP16 (_SDL_HAS_BUILTIN(__builtin_bswap16)) || \ - (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8)) -# define HAS_BUILTIN_BSWAP32 (_SDL_HAS_BUILTIN(__builtin_bswap32)) || \ - (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) -# define HAS_BUILTIN_BSWAP64 (_SDL_HAS_BUILTIN(__builtin_bswap64)) || \ - (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) - - /* this one is broken */ -# define HAS_BROKEN_BSWAP (__GNUC__ == 2 && __GNUC_MINOR__ <= 95) -#else -# define HAS_BUILTIN_BSWAP16 0 -# define HAS_BUILTIN_BSWAP32 0 -# define HAS_BUILTIN_BSWAP64 0 -# define HAS_BROKEN_BSWAP 0 -#endif - -#if HAS_BUILTIN_BSWAP16 -#define SDL_Swap16(x) __builtin_bswap16(x) -#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) -#pragma intrinsic(_byteswap_ushort) -#define SDL_Swap16(x) _byteswap_ushort(x) -#elif defined(__i386__) && !HAS_BROKEN_BSWAP -SDL_FORCE_INLINE Uint16 -SDL_Swap16(Uint16 x) -{ - __asm__("xchgb %b0,%h0": "=q"(x):"0"(x)); - return x; -} -#elif defined(__x86_64__) -SDL_FORCE_INLINE Uint16 -SDL_Swap16(Uint16 x) -{ - __asm__("xchgb %b0,%h0": "=Q"(x):"0"(x)); - return x; -} -#elif (defined(__powerpc__) || defined(__ppc__)) -SDL_FORCE_INLINE Uint16 -SDL_Swap16(Uint16 x) -{ - int result; - - __asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x)); - return (Uint16)result; -} -#elif (defined(__m68k__) && !defined(__mcoldfire__)) -SDL_FORCE_INLINE Uint16 -SDL_Swap16(Uint16 x) -{ - __asm__("rorw #8,%0": "=d"(x): "0"(x):"cc"); - return x; -} -#elif defined(__WATCOMC__) && defined(__386__) -extern __inline Uint16 SDL_Swap16(Uint16); -#pragma aux SDL_Swap16 = \ - "xchg al, ah" \ - parm [ax] \ - modify [ax]; -#else - -/** - * Use this function to swap the byte order of a 16-bit value. - * - * \param x the value to be swapped. - * \returns the swapped value. - * - * \sa SDL_SwapBE16 - * \sa SDL_SwapLE16 - */ -SDL_FORCE_INLINE Uint16 -SDL_Swap16(Uint16 x) -{ - return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); -} -#endif - -#if HAS_BUILTIN_BSWAP32 -#define SDL_Swap32(x) __builtin_bswap32(x) -#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) -#pragma intrinsic(_byteswap_ulong) -#define SDL_Swap32(x) _byteswap_ulong(x) -#elif defined(__i386__) && !HAS_BROKEN_BSWAP -SDL_FORCE_INLINE Uint32 -SDL_Swap32(Uint32 x) -{ - __asm__("bswap %0": "=r"(x):"0"(x)); - return x; -} -#elif defined(__x86_64__) -SDL_FORCE_INLINE Uint32 -SDL_Swap32(Uint32 x) -{ - __asm__("bswapl %0": "=r"(x):"0"(x)); - return x; -} -#elif (defined(__powerpc__) || defined(__ppc__)) -SDL_FORCE_INLINE Uint32 -SDL_Swap32(Uint32 x) -{ - Uint32 result; - - __asm__("rlwimi %0,%2,24,16,23": "=&r"(result): "0" (x>>24), "r"(x)); - __asm__("rlwimi %0,%2,8,8,15" : "=&r"(result): "0" (result), "r"(x)); - __asm__("rlwimi %0,%2,24,0,7" : "=&r"(result): "0" (result), "r"(x)); - return result; -} -#elif (defined(__m68k__) && !defined(__mcoldfire__)) -SDL_FORCE_INLINE Uint32 -SDL_Swap32(Uint32 x) -{ - __asm__("rorw #8,%0\n\tswap %0\n\trorw #8,%0": "=d"(x): "0"(x):"cc"); - return x; -} -#elif defined(__WATCOMC__) && defined(__386__) -extern __inline Uint32 SDL_Swap32(Uint32); -#pragma aux SDL_Swap32 = \ - "bswap eax" \ - parm [eax] \ - modify [eax]; -#else - -/** - * Use this function to swap the byte order of a 32-bit value. - * - * \param x the value to be swapped. - * \returns the swapped value. - * - * \sa SDL_SwapBE32 - * \sa SDL_SwapLE32 - */ -SDL_FORCE_INLINE Uint32 -SDL_Swap32(Uint32 x) -{ - return SDL_static_cast(Uint32, ((x << 24) | ((x << 8) & 0x00FF0000) | - ((x >> 8) & 0x0000FF00) | (x >> 24))); -} -#endif - -#if HAS_BUILTIN_BSWAP64 -#define SDL_Swap64(x) __builtin_bswap64(x) -#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) -#pragma intrinsic(_byteswap_uint64) -#define SDL_Swap64(x) _byteswap_uint64(x) -#elif defined(__i386__) && !HAS_BROKEN_BSWAP -SDL_FORCE_INLINE Uint64 -SDL_Swap64(Uint64 x) -{ - union { - struct { - Uint32 a, b; - } s; - Uint64 u; - } v; - v.u = x; - __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1" - : "=r"(v.s.a), "=r"(v.s.b) - : "0" (v.s.a), "1"(v.s.b)); - return v.u; -} -#elif defined(__x86_64__) -SDL_FORCE_INLINE Uint64 -SDL_Swap64(Uint64 x) -{ - __asm__("bswapq %0": "=r"(x):"0"(x)); - return x; -} -#elif defined(__WATCOMC__) && defined(__386__) -extern __inline Uint64 SDL_Swap64(Uint64); -#pragma aux SDL_Swap64 = \ - "bswap eax" \ - "bswap edx" \ - "xchg eax,edx" \ - parm [eax edx] \ - modify [eax edx]; -#else - -/** - * Use this function to swap the byte order of a 64-bit value. - * - * \param x the value to be swapped. - * \returns the swapped value. - * - * \sa SDL_SwapBE64 - * \sa SDL_SwapLE64 - */ -SDL_FORCE_INLINE Uint64 -SDL_Swap64(Uint64 x) -{ - Uint32 hi, lo; - - /* Separate into high and low 32-bit values and swap them */ - lo = SDL_static_cast(Uint32, x & 0xFFFFFFFF); - x >>= 32; - hi = SDL_static_cast(Uint32, x & 0xFFFFFFFF); - x = SDL_Swap32(lo); - x <<= 32; - x |= SDL_Swap32(hi); - return (x); -} -#endif - - -/** - * Use this function to swap the byte order of a floating point value. - * - * \param x the value to be swapped. - * \returns the swapped value. - * - * \sa SDL_SwapFloatBE - * \sa SDL_SwapFloatLE - */ -SDL_FORCE_INLINE float -SDL_SwapFloat(float x) -{ - union { - float f; - Uint32 ui32; - } swapper; - swapper.f = x; - swapper.ui32 = SDL_Swap32(swapper.ui32); - return swapper.f; -} - -/* remove extra macros */ -#undef HAS_BROKEN_BSWAP -#undef HAS_BUILTIN_BSWAP16 -#undef HAS_BUILTIN_BSWAP32 -#undef HAS_BUILTIN_BSWAP64 - -/** - * \name Swap to native - * Byteswap item from the specified endianness to the native endianness. - */ -/* @{ */ -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_SwapLE16(X) (X) -#define SDL_SwapLE32(X) (X) -#define SDL_SwapLE64(X) (X) -#define SDL_SwapFloatLE(X) (X) -#define SDL_SwapBE16(X) SDL_Swap16(X) -#define SDL_SwapBE32(X) SDL_Swap32(X) -#define SDL_SwapBE64(X) SDL_Swap64(X) -#define SDL_SwapFloatBE(X) SDL_SwapFloat(X) -#else -#define SDL_SwapLE16(X) SDL_Swap16(X) -#define SDL_SwapLE32(X) SDL_Swap32(X) -#define SDL_SwapLE64(X) SDL_Swap64(X) -#define SDL_SwapFloatLE(X) SDL_SwapFloat(X) -#define SDL_SwapBE16(X) (X) -#define SDL_SwapBE32(X) (X) -#define SDL_SwapBE64(X) (X) -#define SDL_SwapFloatBE(X) (X) -#endif -/* @} *//* Swap to native */ - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_endian_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_error.h b/code/thirdparty/SDL2-2.32.8/include/SDL_error.h deleted file mode 100644 index 8d9cde0e77..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_error.h +++ /dev/null @@ -1,163 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryError - * - * Simple error message routines for SDL. - */ - -#ifndef SDL_error_h_ -#define SDL_error_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* Public functions */ - - -/** - * Set the SDL error message for the current thread. - * - * Calling this function will replace any previous error message that was set. - * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: - * - * ```c - * if (error_code) { - * return SDL_SetError("This operation has failed: %d", error_code); - * } - * ``` - * - * \param fmt a printf()-style message format string. - * \param ... additional parameters matching % tokens in the `fmt` string, if - * any. - * \returns always -1. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ClearError - * \sa SDL_GetError - */ -extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); - -/** - * Retrieve a message about the last error that occurred on the current - * thread. - * - * It is possible for multiple errors to occur before calling SDL_GetError(). - * Only the last error is returned. - * - * The message is only applicable when an SDL function has signaled an error. - * You must check the return values of SDL function calls to determine when to - * appropriately call SDL_GetError(). You should *not* use the results of - * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set - * an error string even when reporting success. - * - * SDL will *not* clear the error string for successful API calls. You *must* - * check return values for failure cases before you can assume the error - * string applies. - * - * Error strings are set per-thread, so an error set in a different thread - * will not interfere with the current thread's operation. - * - * The returned string is internally allocated and must not be freed by the - * application. - * - * \returns a message with information about the specific error that occurred, - * or an empty string if there hasn't been an error message set since - * the last call to SDL_ClearError(). The message is only applicable - * when an SDL function has signaled an error. You must check the - * return values of SDL function calls to determine when to - * appropriately call SDL_GetError(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ClearError - * \sa SDL_SetError - */ -extern DECLSPEC const char *SDLCALL SDL_GetError(void); - -/** - * Get the last error message that was set for the current thread. - * - * This allows the caller to copy the error string into a provided buffer, but - * otherwise operates exactly the same as SDL_GetError(). - * - * \param errstr A buffer to fill with the last error message that was set for - * the current thread. - * \param maxlen The size of the buffer pointed to by the errstr parameter. - * \returns the pointer passed in as the `errstr` parameter. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_GetError - */ -extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen); - -/** - * Clear any previous error message for this thread. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetError - * \sa SDL_SetError - */ -extern DECLSPEC void SDLCALL SDL_ClearError(void); - -/** - * \name Internal error functions - * - * \internal - * Private error reporting function - used internally. - */ -/* @{ */ -#define SDL_OutOfMemory() SDL_Error(SDL_ENOMEM) -#define SDL_Unsupported() SDL_Error(SDL_UNSUPPORTED) -#define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) -typedef enum -{ - SDL_ENOMEM, - SDL_EFREAD, - SDL_EFWRITE, - SDL_EFSEEK, - SDL_UNSUPPORTED, - SDL_LASTERROR -} SDL_errorcode; -/* SDL_Error() unconditionally returns -1. */ -extern DECLSPEC int SDLCALL SDL_Error(SDL_errorcode code); -/* @} *//* Internal error functions */ - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_error_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_events.h b/code/thirdparty/SDL2-2.32.8/include/SDL_events.h deleted file mode 100644 index b9596c0ef5..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_events.h +++ /dev/null @@ -1,1196 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryEvents - * - * Include file for SDL event handling. - */ - -#ifndef SDL_events_h_ -#define SDL_events_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_video.h" -#include "SDL_keyboard.h" -#include "SDL_mouse.h" -#include "SDL_joystick.h" -#include "SDL_gamecontroller.h" -#include "SDL_quit.h" -#include "SDL_gesture.h" -#include "SDL_touch.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* General keyboard/mouse state definitions */ -#define SDL_RELEASED 0 -#define SDL_PRESSED 1 - -/** - * The types of events that can be delivered. - */ -typedef enum SDL_EventType -{ - SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */ - - /* Application events */ - SDL_QUIT = 0x100, /**< User-requested quit */ - - /* These application events have special meaning on iOS, see README-ios.md for details */ - SDL_APP_TERMINATING, /**< The application is being terminated by the OS - Called on iOS in applicationWillTerminate() - Called on Android in onDestroy() - */ - SDL_APP_LOWMEMORY, /**< The application is low on memory, free memory if possible. - Called on iOS in applicationDidReceiveMemoryWarning() - Called on Android in onLowMemory() - */ - SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background - Called on iOS in applicationWillResignActive() - Called on Android in onPause() - */ - SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time - Called on iOS in applicationDidEnterBackground() - Called on Android in onPause() - */ - SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground - Called on iOS in applicationWillEnterForeground() - Called on Android in onResume() - */ - SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive - Called on iOS in applicationDidBecomeActive() - Called on Android in onResume() - */ - - SDL_LOCALECHANGED, /**< The user's locale preferences have changed. */ - - /* Display events */ - SDL_DISPLAYEVENT = 0x150, /**< Display state change */ - - /* Window events */ - SDL_WINDOWEVENT = 0x200, /**< Window state change */ - SDL_SYSWMEVENT, /**< System specific event */ - - /* Keyboard events */ - SDL_KEYDOWN = 0x300, /**< Key pressed */ - SDL_KEYUP, /**< Key released */ - SDL_TEXTEDITING, /**< Keyboard text editing (composition) */ - SDL_TEXTINPUT, /**< Keyboard text input */ - SDL_KEYMAPCHANGED, /**< Keymap changed due to a system event such as an - input language or keyboard layout change. - */ - SDL_TEXTEDITING_EXT, /**< Extended keyboard text editing (composition) */ - - /* Mouse events */ - SDL_MOUSEMOTION = 0x400, /**< Mouse moved */ - SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */ - SDL_MOUSEBUTTONUP, /**< Mouse button released */ - SDL_MOUSEWHEEL, /**< Mouse wheel motion */ - - /* Joystick events */ - SDL_JOYAXISMOTION = 0x600, /**< Joystick axis motion */ - SDL_JOYBALLMOTION, /**< Joystick trackball motion */ - SDL_JOYHATMOTION, /**< Joystick hat position change */ - SDL_JOYBUTTONDOWN, /**< Joystick button pressed */ - SDL_JOYBUTTONUP, /**< Joystick button released */ - SDL_JOYDEVICEADDED, /**< A new joystick has been inserted into the system */ - SDL_JOYDEVICEREMOVED, /**< An opened joystick has been removed */ - SDL_JOYBATTERYUPDATED, /**< Joystick battery level change */ - - /* Game controller events */ - SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */ - SDL_CONTROLLERBUTTONDOWN, /**< Game controller button pressed */ - SDL_CONTROLLERBUTTONUP, /**< Game controller button released */ - SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */ - SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */ - SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */ - SDL_CONTROLLERTOUCHPADDOWN, /**< Game controller touchpad was touched */ - SDL_CONTROLLERTOUCHPADMOTION, /**< Game controller touchpad finger was moved */ - SDL_CONTROLLERTOUCHPADUP, /**< Game controller touchpad finger was lifted */ - SDL_CONTROLLERSENSORUPDATE, /**< Game controller sensor was updated */ - SDL_CONTROLLERUPDATECOMPLETE_RESERVED_FOR_SDL3, - SDL_CONTROLLERSTEAMHANDLEUPDATED, /**< Game controller Steam handle has changed */ - - /* Touch events */ - SDL_FINGERDOWN = 0x700, - SDL_FINGERUP, - SDL_FINGERMOTION, - - /* Gesture events */ - SDL_DOLLARGESTURE = 0x800, - SDL_DOLLARRECORD, - SDL_MULTIGESTURE, - - /* Clipboard events */ - SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard or primary selection changed */ - - /* Drag and drop events */ - SDL_DROPFILE = 0x1000, /**< The system requests a file open */ - SDL_DROPTEXT, /**< text/plain drag-and-drop event */ - SDL_DROPBEGIN, /**< A new set of drops is beginning (NULL filename) */ - SDL_DROPCOMPLETE, /**< Current set of drops is now complete (NULL filename) */ - - /* Audio hotplug events */ - SDL_AUDIODEVICEADDED = 0x1100, /**< A new audio device is available */ - SDL_AUDIODEVICEREMOVED, /**< An audio device has been removed. */ - - /* Sensor events */ - SDL_SENSORUPDATE = 0x1200, /**< A sensor was updated */ - - /* Render events */ - SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ - SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ - - /* Internal events */ - SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ - - /** Events SDL_USEREVENT through SDL_LASTEVENT are for your use, - * and should be allocated with SDL_RegisterEvents() - */ - SDL_USEREVENT = 0x8000, - - /** - * This last event is only for bounding internal arrays - */ - SDL_LASTEVENT = 0xFFFF -} SDL_EventType; - -/** - * Fields shared by every event - */ -typedef struct SDL_CommonEvent -{ - Uint32 type; - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ -} SDL_CommonEvent; - -/** - * Display state change event data (event.display.*) - */ -typedef struct SDL_DisplayEvent -{ - Uint32 type; /**< SDL_DISPLAYEVENT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 display; /**< The associated display index */ - Uint8 event; /**< SDL_DisplayEventID */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; - Sint32 data1; /**< event dependent data */ -} SDL_DisplayEvent; - -/** - * Window state change event data (event.window.*) - */ -typedef struct SDL_WindowEvent -{ - Uint32 type; /**< SDL_WINDOWEVENT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The associated window */ - Uint8 event; /**< SDL_WindowEventID */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; - Sint32 data1; /**< event dependent data */ - Sint32 data2; /**< event dependent data */ -} SDL_WindowEvent; - -/** - * Keyboard button event structure (event.key.*) - */ -typedef struct SDL_KeyboardEvent -{ - Uint32 type; /**< SDL_KEYDOWN or SDL_KEYUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with keyboard focus, if any */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ - Uint8 padding2; - Uint8 padding3; - SDL_Keysym keysym; /**< The key that was pressed or released */ -} SDL_KeyboardEvent; - -#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) - -/** - * Keyboard text editing event structure (event.edit.*) - */ -typedef struct SDL_TextEditingEvent -{ - Uint32 type; /**< SDL_TEXTEDITING */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with keyboard focus, if any */ - char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ - Sint32 start; /**< The start cursor of selected editing text */ - Sint32 length; /**< The length of selected editing text */ -} SDL_TextEditingEvent; - -/** - * Extended keyboard text editing event structure (event.editExt.*) when text - * would be truncated if stored in the text buffer SDL_TextEditingEvent - */ -typedef struct SDL_TextEditingExtEvent -{ - Uint32 type; /**< SDL_TEXTEDITING_EXT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with keyboard focus, if any */ - char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */ - Sint32 start; /**< The start cursor of selected editing text */ - Sint32 length; /**< The length of selected editing text */ -} SDL_TextEditingExtEvent; - -/** - * The maximum bytes of text that can be supplied in an SDL_TextInputEvent. - */ -#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) - -/** - * Keyboard text input event structure (event.text.*) - * - * `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming - * string is larger than this, SDL will split it and send it in pieces, across - * multiple events. The string is in UTF-8 format, and if split, SDL - * guarantees that it will not split in the middle of a UTF-8 sequence, so any - * event will only contain complete codepoints. However, if there are several - * codepoints that go together into a single glyph (like an emoji "thumbs up" - * followed by a skin color), they may be split between events. - * - * This event will never be delivered unless text input is enabled by calling - * SDL_StartTextInput(). Text input is enabled by default on desktop - * platforms, and disabled by default on mobile platforms! - * - * \sa SDL_StartTextInput - * \sa SDL_StopTextInput - */ -typedef struct SDL_TextInputEvent -{ - Uint32 type; /**< SDL_TEXTINPUT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with keyboard focus, if any */ - char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text; UTF-8 encoded. */ -} SDL_TextInputEvent; - -/** - * Mouse motion event structure (event.motion.*) - */ -typedef struct SDL_MouseMotionEvent -{ - Uint32 type; /**< SDL_MOUSEMOTION */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with mouse focus, if any */ - Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ - Uint32 state; /**< The current button state */ - Sint32 x; /**< X coordinate, relative to window */ - Sint32 y; /**< Y coordinate, relative to window */ - Sint32 xrel; /**< The relative motion in the X direction */ - Sint32 yrel; /**< The relative motion in the Y direction */ -} SDL_MouseMotionEvent; - -/** - * Mouse button event structure (event.button.*) - */ -typedef struct SDL_MouseButtonEvent -{ - Uint32 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with mouse focus, if any */ - Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ - Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ - Uint8 padding1; - Sint32 x; /**< X coordinate, relative to window */ - Sint32 y; /**< Y coordinate, relative to window */ -} SDL_MouseButtonEvent; - -/** - * Mouse wheel event structure (event.wheel.*) - */ -typedef struct SDL_MouseWheelEvent -{ - Uint32 type; /**< SDL_MOUSEWHEEL */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The window with mouse focus, if any */ - Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ - Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ - Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ - Uint32 direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ - float preciseX; /**< The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) */ - float preciseY; /**< The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) */ - Sint32 mouseX; /**< X coordinate, relative to window (added in 2.26.0) */ - Sint32 mouseY; /**< Y coordinate, relative to window (added in 2.26.0) */ -} SDL_MouseWheelEvent; - -/** - * Joystick axis motion event structure (event.jaxis.*) - */ -typedef struct SDL_JoyAxisEvent -{ - Uint32 type; /**< SDL_JOYAXISMOTION */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 axis; /**< The joystick axis index */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; - Sint16 value; /**< The axis value (range: -32768 to 32767) */ - Uint16 padding4; -} SDL_JoyAxisEvent; - -/** - * Joystick trackball motion event structure (event.jball.*) - */ -typedef struct SDL_JoyBallEvent -{ - Uint32 type; /**< SDL_JOYBALLMOTION */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 ball; /**< The joystick trackball index */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; - Sint16 xrel; /**< The relative motion in the X direction */ - Sint16 yrel; /**< The relative motion in the Y direction */ -} SDL_JoyBallEvent; - -/** - * Joystick hat position change event structure (event.jhat.*) - */ -typedef struct SDL_JoyHatEvent -{ - Uint32 type; /**< SDL_JOYHATMOTION */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 hat; /**< The joystick hat index */ - Uint8 value; /**< The hat position value. - * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP - * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT - * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN - * - * Note that zero means the POV is centered. - */ - Uint8 padding1; - Uint8 padding2; -} SDL_JoyHatEvent; - -/** - * Joystick button event structure (event.jbutton.*) - */ -typedef struct SDL_JoyButtonEvent -{ - Uint32 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 padding1; - Uint8 padding2; -} SDL_JoyButtonEvent; - -/** - * Joystick device event structure (event.jdevice.*) - * - * SDL will send JOYSTICK_ADDED events for devices that are already plugged in - * during SDL_Init. - * - * \sa SDL_ControllerDeviceEvent - */ -typedef struct SDL_JoyDeviceEvent -{ - Uint32 type; /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */ -} SDL_JoyDeviceEvent; - -/** - * Joysick battery level change event structure (event.jbattery.*) - */ -typedef struct SDL_JoyBatteryEvent -{ - Uint32 type; /**< SDL_JOYBATTERYUPDATED */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - SDL_JoystickPowerLevel level; /**< The joystick battery level */ -} SDL_JoyBatteryEvent; - -/** - * Game controller axis motion event structure (event.caxis.*) - */ -typedef struct SDL_ControllerAxisEvent -{ - Uint32 type; /**< SDL_CONTROLLERAXISMOTION */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; - Sint16 value; /**< The axis value (range: -32768 to 32767) */ - Uint16 padding4; -} SDL_ControllerAxisEvent; - - -/** - * Game controller button event structure (event.cbutton.*) - */ -typedef struct SDL_ControllerButtonEvent -{ - Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Uint8 button; /**< The controller button (SDL_GameControllerButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 padding1; - Uint8 padding2; -} SDL_ControllerButtonEvent; - - -/** - * Controller device event structure (event.cdevice.*) - * - * Joysticks that are supported game controllers receive both an - * SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent. - * - * SDL will send CONTROLLERDEVICEADDED events for joysticks that are already - * plugged in during SDL_Init() and are recognized as game controllers. - */ -typedef struct SDL_ControllerDeviceEvent -{ - Uint32 type; /**< SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED, or SDL_CONTROLLERSTEAMHANDLEUPDATED */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */ -} SDL_ControllerDeviceEvent; - -/** - * Game controller touchpad event structure (event.ctouchpad.*) - */ -typedef struct SDL_ControllerTouchpadEvent -{ - Uint32 type; /**< SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Sint32 touchpad; /**< The index of the touchpad */ - Sint32 finger; /**< The index of the finger on the touchpad */ - float x; /**< Normalized in the range 0...1 with 0 being on the left */ - float y; /**< Normalized in the range 0...1 with 0 being at the top */ - float pressure; /**< Normalized in the range 0...1 */ -} SDL_ControllerTouchpadEvent; - -/** - * Game controller sensor event structure (event.csensor.*) - */ -typedef struct SDL_ControllerSensorEvent -{ - Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_JoystickID which; /**< The joystick instance id */ - Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */ - float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ - Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */ -} SDL_ControllerSensorEvent; - -/** - * Audio device event structure (event.adevice.*) - */ -typedef struct SDL_AudioDeviceEvent -{ - Uint32 type; /**< SDL_AUDIODEVICEADDED, or SDL_AUDIODEVICEREMOVED */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */ - Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */ - Uint8 padding1; - Uint8 padding2; - Uint8 padding3; -} SDL_AudioDeviceEvent; - - -/** - * Touch finger event structure (event.tfinger.*) - */ -typedef struct SDL_TouchFingerEvent -{ - Uint32 type; /**< SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_TouchID touchId; /**< The touch device id */ - SDL_FingerID fingerId; - float x; /**< Normalized in the range 0...1 */ - float y; /**< Normalized in the range 0...1 */ - float dx; /**< Normalized in the range -1...1 */ - float dy; /**< Normalized in the range -1...1 */ - float pressure; /**< Normalized in the range 0...1 */ - Uint32 windowID; /**< The window underneath the finger, if any */ -} SDL_TouchFingerEvent; - - -/** - * Multiple Finger Gesture Event (event.mgesture.*) - */ -typedef struct SDL_MultiGestureEvent -{ - Uint32 type; /**< SDL_MULTIGESTURE */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_TouchID touchId; /**< The touch device id */ - float dTheta; - float dDist; - float x; - float y; - Uint16 numFingers; - Uint16 padding; -} SDL_MultiGestureEvent; - - -/** - * Dollar Gesture Event (event.dgesture.*) - */ -typedef struct SDL_DollarGestureEvent -{ - Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_TouchID touchId; /**< The touch device id */ - SDL_GestureID gestureId; - Uint32 numFingers; - float error; - float x; /**< Normalized center of gesture */ - float y; /**< Normalized center of gesture */ -} SDL_DollarGestureEvent; - - -/** - * An event used to request a file open by the system (event.drop.*) - * - * This event is enabled by default, you can disable it with SDL_EventState(). - * - * If this event is enabled, you must free the filename in the event. - */ -typedef struct SDL_DropEvent -{ - Uint32 type; /**< SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */ - Uint32 windowID; /**< The window that was dropped on, if any */ -} SDL_DropEvent; - - -/** - * Sensor event structure (event.sensor.*) - */ -typedef struct SDL_SensorEvent -{ - Uint32 type; /**< SDL_SENSORUPDATE */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Sint32 which; /**< The instance ID of the sensor */ - float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */ - Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */ -} SDL_SensorEvent; - -/** - * The "quit requested" event - */ -typedef struct SDL_QuitEvent -{ - Uint32 type; /**< SDL_QUIT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ -} SDL_QuitEvent; - -/** - * A user-defined event type (event.user.*) - */ -typedef struct SDL_UserEvent -{ - Uint32 type; /**< SDL_USEREVENT through SDL_LASTEVENT-1 */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - Uint32 windowID; /**< The associated window if any */ - Sint32 code; /**< User defined event code */ - void *data1; /**< User defined data pointer */ - void *data2; /**< User defined data pointer */ -} SDL_UserEvent; - - -struct SDL_SysWMmsg; -typedef struct SDL_SysWMmsg SDL_SysWMmsg; - -/** - * A video driver dependent system event (event.syswm.*) - * - * This event is disabled by default, you can enable it with SDL_EventState() - * - * If you want to use this event, you should include SDL_syswm.h. - */ -typedef struct SDL_SysWMEvent -{ - Uint32 type; /**< SDL_SYSWMEVENT */ - Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ - SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ -} SDL_SysWMEvent; - -/** - * General event structure - * - * The SDL_Event structure is the core of all event handling in SDL. SDL_Event - * is a union of all event structures used in SDL. - */ -typedef union SDL_Event -{ - Uint32 type; /**< Event type, shared with all events */ - SDL_CommonEvent common; /**< Common event data */ - SDL_DisplayEvent display; /**< Display event data */ - SDL_WindowEvent window; /**< Window event data */ - SDL_KeyboardEvent key; /**< Keyboard event data */ - SDL_TextEditingEvent edit; /**< Text editing event data */ - SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */ - SDL_TextInputEvent text; /**< Text input event data */ - SDL_MouseMotionEvent motion; /**< Mouse motion event data */ - SDL_MouseButtonEvent button; /**< Mouse button event data */ - SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */ - SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */ - SDL_JoyBallEvent jball; /**< Joystick ball event data */ - SDL_JoyHatEvent jhat; /**< Joystick hat event data */ - SDL_JoyButtonEvent jbutton; /**< Joystick button event data */ - SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */ - SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */ - SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */ - SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */ - SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */ - SDL_ControllerTouchpadEvent ctouchpad; /**< Game Controller touchpad event data */ - SDL_ControllerSensorEvent csensor; /**< Game Controller sensor event data */ - SDL_AudioDeviceEvent adevice; /**< Audio device event data */ - SDL_SensorEvent sensor; /**< Sensor event data */ - SDL_QuitEvent quit; /**< Quit request event data */ - SDL_UserEvent user; /**< Custom event data */ - SDL_SysWMEvent syswm; /**< System dependent window event data */ - SDL_TouchFingerEvent tfinger; /**< Touch finger event data */ - SDL_MultiGestureEvent mgesture; /**< Gesture event data */ - SDL_DollarGestureEvent dgesture; /**< Gesture event data */ - SDL_DropEvent drop; /**< Drag and drop event data */ - - /* This is necessary for ABI compatibility between Visual C++ and GCC. - Visual C++ will respect the push pack pragma and use 52 bytes (size of - SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit - architectures) for this union, and GCC will use the alignment of the - largest datatype within the union, which is 8 bytes on 64-bit - architectures. - - So... we'll add padding to force the size to be 56 bytes for both. - - On architectures where pointers are 16 bytes, this needs rounding up to - the next multiple of 16, 64, and on architectures where pointers are - even larger the size of SDL_UserEvent will dominate as being 3 pointers. - */ - Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)]; -} SDL_Event; - -/* Make sure we haven't broken binary compatibility */ -SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding)); - - -/* Function prototypes */ - -/** - * Pump the event loop, gathering events from the input devices. - * - * This function updates the event queue and internal input device state. - * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * - * SDL_PumpEvents() gathers all the pending input information from devices and - * places it in the event queue. Without calls to SDL_PumpEvents() no events - * would ever be placed on the queue. Often the need for calls to - * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and - * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not - * polling or waiting for events (e.g. you are filtering them), then you must - * call SDL_PumpEvents() to force an event queue update. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PollEvent - * \sa SDL_WaitEvent - */ -extern DECLSPEC void SDLCALL SDL_PumpEvents(void); - -/* @{ */ -typedef enum SDL_eventaction -{ - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT -} SDL_eventaction; - -/** - * Check the event queue for messages and optionally return them. - * - * `action` may be any of the following: - * - * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the - * event queue. - * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, - * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. - * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, - * within the specified minimum and maximum type, will be returned to the - * caller and will be removed from the queue. - * - * You may have to call SDL_PumpEvents() before calling this function. - * Otherwise, the events may not be ready to be filtered when you call - * SDL_PeepEvents(). - * - * This function is thread-safe. - * - * \param events destination buffer for the retrieved events. - * \param numevents if action is SDL_ADDEVENT, the number of events to add - * back to the event queue; if action is SDL_PEEKEVENT or - * SDL_GETEVENT, the maximum number of events to retrieve. - * \param action action to take; see [[#action|Remarks]] for details. - * \param minType minimum value of the event type to be considered; - * SDL_FIRSTEVENT is a safe choice. - * \param maxType maximum value of the event type to be considered; - * SDL_LASTEVENT is a safe choice. - * \returns the number of events actually stored or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PollEvent - * \sa SDL_PumpEvents - * \sa SDL_PushEvent - */ -extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, - SDL_eventaction action, - Uint32 minType, Uint32 maxType); -/* @} */ - -/** - * Check for the existence of a certain event type in the event queue. - * - * If you need to check for a range of event types, use SDL_HasEvents() - * instead. - * - * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasEvents - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); - - -/** - * Check for the existence of certain event types in the event queue. - * - * If you need to check for a single event type, use SDL_HasEvent() instead. - * - * \param minType the low end of event type to be queried, inclusive; see - * SDL_EventType for details. - * \param maxType the high end of event type to be queried, inclusive; see - * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasEvents - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); - -/** - * Clear events of a specific type from the event queue. - * - * This will unconditionally remove any events from the queue that match - * `type`. If you need to remove a range of event types, use SDL_FlushEvents() - * instead. - * - * It's also normal to just ignore events you don't care about in your event - * loop without calling this function. - * - * This function only affects currently queued events. If you want to make - * sure that all pending OS events are flushed, you can call SDL_PumpEvents() - * on the main thread immediately before the flush call. - * - * \param type the type of event to be cleared; see SDL_EventType for details. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FlushEvents - */ -extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); - -/** - * Clear events of a range of types from the event queue. - * - * This will unconditionally remove any events from the queue that are in the - * range of `minType` to `maxType`, inclusive. If you need to remove a single - * event type, use SDL_FlushEvent() instead. - * - * It's also normal to just ignore events you don't care about in your event - * loop without calling this function. - * - * This function only affects currently queued events. If you want to make - * sure that all pending OS events are flushed, you can call SDL_PumpEvents() - * on the main thread immediately before the flush call. - * - * \param minType the low end of event type to be cleared, inclusive; see - * SDL_EventType for details. - * \param maxType the high end of event type to be cleared, inclusive; see - * SDL_EventType for details. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FlushEvent - */ -extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); - -/** - * Poll for currently pending events. - * - * If `event` is not NULL, the next event is removed from the queue and stored - * in the SDL_Event structure pointed to by `event`. The 1 returned refers to - * this event, immediately stored in the SDL Event structure -- not an event - * to follow. - * - * If `event` is NULL, it simply returns 1 if there is an event in the queue, - * but will not remove it from the queue. - * - * As this function may implicitly call SDL_PumpEvents(), you can only call - * this function in the thread that set the video mode. - * - * SDL_PollEvent() is the favored way of receiving system events since it can - * be done from the main loop and does not suspend the main loop while waiting - * on an event to be posted. - * - * The common practice is to fully process the event queue once every frame, - * usually as a first step before updating the game's state: - * - * ```c - * while (game_is_still_running) { - * SDL_Event event; - * while (SDL_PollEvent(&event)) { // poll until all events are handled! - * // decide what to do with this event. - * } - * - * // update game state, draw the current frame - * } - * ``` - * - * \param event the SDL_Event structure to be filled with the next event from - * the queue, or NULL. - * \returns 1 if there is a pending event or 0 if there are none available. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetEventFilter - * \sa SDL_PeepEvents - * \sa SDL_PushEvent - * \sa SDL_SetEventFilter - * \sa SDL_WaitEvent - * \sa SDL_WaitEventTimeout - */ -extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); - -/** - * Wait indefinitely for the next available event. - * - * If `event` is not NULL, the next event is removed from the queue and stored - * in the SDL_Event structure pointed to by `event`. - * - * As this function may implicitly call SDL_PumpEvents(), you can only call - * this function in the thread that initialized the video subsystem. - * - * \param event the SDL_Event structure to be filled in with the next event - * from the queue, or NULL. - * \returns 1 on success or 0 if there was an error while waiting for events; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PollEvent - * \sa SDL_PumpEvents - * \sa SDL_WaitEventTimeout - */ -extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); - -/** - * Wait until the specified timeout (in milliseconds) for the next available - * event. - * - * If `event` is not NULL, the next event is removed from the queue and stored - * in the SDL_Event structure pointed to by `event`. - * - * As this function may implicitly call SDL_PumpEvents(), you can only call - * this function in the thread that initialized the video subsystem. - * - * \param event the SDL_Event structure to be filled in with the next event - * from the queue, or NULL. - * \param timeout the maximum number of milliseconds to wait for the next - * available event. - * \returns 1 on success or 0 if there was an error while waiting for events; - * call SDL_GetError() for more information. This also returns 0 if - * the timeout elapsed without an event arriving. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PollEvent - * \sa SDL_PumpEvents - * \sa SDL_WaitEvent - */ -extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, - int timeout); - -/** - * Add an event to the event queue. - * - * The event queue can actually be used as a two way communication channel. - * Not only can events be read from the queue, but the user can also push - * their own events onto it. `event` is a pointer to the event structure you - * wish to push onto the queue. The event is copied into the queue, and the - * caller may dispose of the memory pointed to after SDL_PushEvent() returns. - * - * Note: Pushing device input events onto the queue doesn't modify the state - * of the device within SDL. - * - * This function is thread-safe, and can be called from other threads safely. - * - * Note: Events pushed onto the queue with SDL_PushEvent() get passed through - * the event filter but events added with SDL_PeepEvents() do not. - * - * For pushing application-specific events, please use SDL_RegisterEvents() to - * get an event type that does not conflict with other code that also wants - * its own custom event types. - * - * \param event the SDL_Event to be added to the queue. - * \returns 1 on success, 0 if the event was filtered, or a negative error - * code on failure; call SDL_GetError() for more information. A - * common reason for error is the event queue being full. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PeepEvents - * \sa SDL_PollEvent - * \sa SDL_RegisterEvents - */ -extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event); - -/** - * A function pointer used for callbacks that watch the event queue. - * - * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or - * SDL_AddEventWatch, etc. - * \param event the event that triggered the callback. - * \returns 1 to permit event to be added to the queue, and 0 to disallow it. - * When used with SDL_AddEventWatch, the return value is ignored. - * - * \sa SDL_SetEventFilter - * \sa SDL_AddEventWatch - */ -typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); - -/** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. - * - * If the filter function returns 1 when called, then the event will be added - * to the internal queue. If it returns 0, then the event will be dropped from - * the queue, but the internal state will still be updated. This allows - * selective filtering of dynamically arriving events. - * - * **WARNING**: Be very careful of what you do in the event filter function, - * as it may run in a different thread! - * - * On platforms that support it, if the quit event is generated by an - * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the - * application at the next event poll. - * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * - * Note: Disabled events never make it to the event filter function; see - * SDL_EventState(). - * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * - * Note: Events pushed onto the queue with SDL_PushEvent() get passed through - * the event filter, but events pushed onto the queue with SDL_PeepEvents() do - * not. - * - * \param filter An SDL_EventFilter function to call when an event happens. - * \param userdata a pointer that is passed to `filter`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AddEventWatch - * \sa SDL_EventState - * \sa SDL_GetEventFilter - * \sa SDL_PeepEvents - * \sa SDL_PushEvent - */ -extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, - void *userdata); - -/** - * Query the current event filter. - * - * This function can be used to "chain" filters, by saving the existing filter - * before replacing it with a function that will call that saved filter. - * - * \param filter the current callback function will be stored here. - * \param userdata the pointer that is passed to the current event filter will - * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetEventFilter - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, - void **userdata); - -/** - * Add a callback to be triggered when an event is added to the event queue. - * - * `filter` will be called when an event happens, and its return value is - * ignored. - * - * **WARNING**: Be very careful of what you do in the event filter function, - * as it may run in a different thread! - * - * If the quit event is generated by a signal (e.g. SIGINT), it will bypass - * the internal queue and be delivered to the watch callback immediately, and - * arrive at the next event poll. - * - * Note: the callback is called for events posted by the user through - * SDL_PushEvent(), but not for disabled events, nor for events by a filter - * callback set with SDL_SetEventFilter(), nor for events posted by the user - * through SDL_PeepEvents(). - * - * \param filter an SDL_EventFilter function to call when an event happens. - * \param userdata a pointer that is passed to `filter`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DelEventWatch - * \sa SDL_SetEventFilter - */ -extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, - void *userdata); - -/** - * Remove an event watch callback added with SDL_AddEventWatch(). - * - * This function takes the same input as SDL_AddEventWatch() to identify and - * delete the corresponding callback. - * - * \param filter the function originally passed to SDL_AddEventWatch(). - * \param userdata the pointer originally passed to SDL_AddEventWatch(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AddEventWatch - */ -extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, - void *userdata); - -/** - * Run a specific filter function on the current event queue, removing any - * events for which the filter returns 0. - * - * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), - * this function does not change the filter permanently, it only uses the - * supplied filter until this function returns. - * - * \param filter the SDL_EventFilter function to call when an event happens. - * \param userdata a pointer that is passed to `filter`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetEventFilter - * \sa SDL_SetEventFilter - */ -extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, - void *userdata); - -/* @{ */ -#define SDL_QUERY -1 -#define SDL_IGNORE 0 -#define SDL_DISABLE 0 -#define SDL_ENABLE 1 - -/** - * Set the state of processing events by type. - * - * `state` may be any of the following: - * - * - `SDL_QUERY`: returns the current processing state of the specified event - * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped - * from the event queue and will not be filtered - * - `SDL_ENABLE`: the event will be processed normally - * - * \param type the type of event; see SDL_EventType for details. - * \param state how to process the event. - * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state - * of the event before this function makes any changes to it. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetEventState - */ -extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); -/* @} */ -#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY) - -/** - * Allocate a set of user-defined events, and return the beginning event - * number for that set of events. - * - * Calling this function with `numevents` <= 0 is an error and will return - * (Uint32)-1. - * - * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or - * 0xFFFFFFFF), but is clearer to write. - * - * \param numevents the number of events to be allocated. - * \returns the beginning event number, or (Uint32)-1 if there are not enough - * user-defined events left. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PushEvent - */ -extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_events_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_filesystem.h b/code/thirdparty/SDL2-2.32.8/include/SDL_filesystem.h deleted file mode 100644 index c72a6165fe..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_filesystem.h +++ /dev/null @@ -1,149 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryFilesystem - * - * Include file for filesystem SDL API functions - */ - -#ifndef SDL_filesystem_h_ -#define SDL_filesystem_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" - -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Get the directory where the application was run from. - * - * This is not necessarily a fast call, so you should call this once near - * startup and save the string if you need it. - * - * **Mac OS X and iOS Specific Functionality**: If the application is in a - * ".app" bundle, this function returns the Resource directory (e.g. - * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding - * a property to the Info.plist file. Adding a string key with the name - * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the - * behaviour. - * - * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an - * application in /Applications/SDLApp/MyApp.app): - * - * - `resource`: bundle resource directory (the default). For example: - * `/Applications/SDLApp/MyApp.app/Contents/Resources` - * - `bundle`: the Bundle directory. For example: - * `/Applications/SDLApp/MyApp.app/` - * - `parent`: the containing directory of the bundle. For example: - * `/Applications/SDLApp/` - * - * **Nintendo 3DS Specific Functionality**: This function returns "romfs" - * directory of the application as it is uncommon to store resources outside - * the executable. As such it is not a writable directory. - * - * The returned path is guaranteed to end with a path separator ('\\' on - * Windows, '/' on most other platforms). - * - * The pointer returned is owned by the caller. Please call SDL_free() on the - * pointer when done with it. - * - * \returns an absolute path in UTF-8 encoding to the application data - * directory. NULL will be returned on error or when the platform - * doesn't implement this functionality, call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.1. - * - * \sa SDL_GetPrefPath - */ -extern DECLSPEC char *SDLCALL SDL_GetBasePath(void); - -/** - * Get the user-and-app-specific path where files can be written. - * - * Get the "pref dir". This is meant to be where users can write personal - * files (preferences and save games, etc) that are specific to your - * application. This directory is unique per user, per application. - * - * This function will decide the appropriate location in the native - * filesystem, create the directory if necessary, and return a string of the - * absolute path to the directory in UTF-8 encoding. - * - * On Windows, the string might look like: - * - * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\` - * - * On Linux, the string might look like: - * - * `/home/bob/.local/share/My Program Name/` - * - * On Mac OS X, the string might look like: - * - * `/Users/bob/Library/Application Support/My Program Name/` - * - * You should assume the path returned by this function is the only safe place - * to write files (and that SDL_GetBasePath(), while it might be writable, or - * even the parent of the returned path, isn't where you should be writing - * things). - * - * Both the org and app strings may become part of a directory name, so please - * follow these rules: - * - * - Try to use the same org string (_including case-sensitivity_) for all - * your applications that use this function. - * - Always use a unique app string for each one, and make sure it never - * changes for an app once you've decided on it. - * - Unicode characters are legal, as long as it's UTF-8 encoded, but... - * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game - * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. - * - * The returned path is guaranteed to end with a path separator ('\\' on - * Windows, '/' on most other platforms). - * - * The pointer returned is owned by the caller. Please call SDL_free() on the - * pointer when done with it. - * - * \param org the name of your organization. - * \param app the name of your application. - * \returns a UTF-8 string of the user directory in platform-dependent - * notation. NULL if there's a problem (creating directory failed, - * etc.). - * - * \since This function is available since SDL 2.0.1. - * - * \sa SDL_GetBasePath - */ -extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_filesystem_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_gamecontroller.h b/code/thirdparty/SDL2-2.32.8/include/SDL_gamecontroller.h deleted file mode 100644 index 4d8bcce22b..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_gamecontroller.h +++ /dev/null @@ -1,1110 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: GameController */ - -/** - * # CategoryGameController - * - * Include file for SDL game controller event handling - */ - -#ifndef SDL_gamecontroller_h_ -#define SDL_gamecontroller_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_rwops.h" -#include "SDL_sensor.h" -#include "SDL_joystick.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \file SDL_gamecontroller.h - * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system - * for game controllers, and load appropriate drivers. - * - * If you would like to receive controller updates while the application - * is in the background, you should set the following hint before calling - * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS - */ - -/** - * The gamecontroller structure used to identify an SDL game controller - */ -struct _SDL_GameController; -typedef struct _SDL_GameController SDL_GameController; - -typedef enum SDL_GameControllerType -{ - SDL_CONTROLLER_TYPE_UNKNOWN = 0, - SDL_CONTROLLER_TYPE_XBOX360, - SDL_CONTROLLER_TYPE_XBOXONE, - SDL_CONTROLLER_TYPE_PS3, - SDL_CONTROLLER_TYPE_PS4, - SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO, - SDL_CONTROLLER_TYPE_VIRTUAL, - SDL_CONTROLLER_TYPE_PS5, - SDL_CONTROLLER_TYPE_AMAZON_LUNA, - SDL_CONTROLLER_TYPE_GOOGLE_STADIA, - SDL_CONTROLLER_TYPE_NVIDIA_SHIELD, - SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, - SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, - SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_CONTROLLER_TYPE_MAX -} SDL_GameControllerType; - -typedef enum SDL_GameControllerBindType -{ - SDL_CONTROLLER_BINDTYPE_NONE = 0, - SDL_CONTROLLER_BINDTYPE_BUTTON, - SDL_CONTROLLER_BINDTYPE_AXIS, - SDL_CONTROLLER_BINDTYPE_HAT -} SDL_GameControllerBindType; - -/** - * Get the SDL joystick layer binding for this controller button/axis mapping - */ -typedef struct SDL_GameControllerButtonBind -{ - SDL_GameControllerBindType bindType; - union - { - int button; - int axis; - struct { - int hat; - int hat_mask; - } hat; - } value; - -} SDL_GameControllerButtonBind; - - -/** - * To count the number of game controllers in the system for the following: - * - * ```c - * int nJoysticks = SDL_NumJoysticks(); - * int nGameControllers = 0; - * for (int i = 0; i < nJoysticks; i++) { - * if (SDL_IsGameController(i)) { - * nGameControllers++; - * } - * } - * ``` - * - * Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is: - * guid,name,mappings - * - * Where GUID is the string value from SDL_JoystickGetGUIDString(), name is the human readable string for the device and mappings are controller mappings to joystick ones. - * Under Windows there is a reserved GUID of "xinput" that covers any XInput devices. - * The mapping format for joystick is: - * bX - a joystick button, index X - * hX.Y - hat X with value Y - * aX - axis X of the joystick - * Buttons can be used as a controller axis and vice versa. - * - * This string shows an example of a valid mapping for a controller - * - * ```c - * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7", - * ``` - */ - -/** - * Load a set of Game Controller mappings from a seekable SDL data stream. - * - * You can call this function several times, if needed, to load different - * database files. - * - * If a new mapping is loaded for an already known controller GUID, the later - * version will overwrite the one currently loaded. - * - * If this function is called before SDL_Init, SDL will generate an - * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged - * in at the time that SDL_Init is called. - * - * Mappings not belonging to the current platform or with no platform field - * specified will be ignored (i.e. mappings for Linux will be ignored in - * Windows, etc). - * - * This function will load the text database entirely in memory before - * processing it, so take this into consideration if you are in a memory - * constrained environment. - * - * \param rw the data stream for the mappings to be added. - * \param freerw non-zero to close the stream after being read. - * \returns the number of mappings added or -1 on error; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_GameControllerAddMapping - * \sa SDL_GameControllerAddMappingsFromFile - * \sa SDL_GameControllerMappingForGUID - * \sa SDL_CONTROLLERDEVICEADDED - */ -extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw); - -/** - * Load a set of mappings from a file, filtered by the current - * SDL_GetPlatform() - * - * Convenience macro. - */ -#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) - -/** - * Add support for controllers that SDL is unaware of or to cause an existing - * controller to have a different binding. - * - * The mapping string has the format "GUID,name,mapping", where GUID is the - * string value from SDL_JoystickGetGUIDString(), name is the human readable - * string for the device and mappings are controller mappings to joystick - * ones. Under Windows there is a reserved GUID of "xinput" that covers all - * XInput devices. The mapping format for joystick is: {| |bX |a joystick - * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick - * |} Buttons can be used as a controller axes and vice versa. - * - * This string shows an example of a valid mapping for a controller: - * - * ```c - * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7" - * ``` - * - * If this function is called before SDL_Init, SDL will generate an - * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged - * in at the time that SDL_Init is called. - * - * \param mappingString the mapping string. - * \returns 1 if a new mapping is added, 0 if an existing mapping is updated, - * -1 on error; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerMapping - * \sa SDL_GameControllerMappingForGUID - * \sa SDL_CONTROLLERDEVICEADDED - */ -extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString); - -/** - * Get the number of mappings installed. - * - * \returns the number of mappings. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void); - -/** - * Get the mapping at a particular index. - * - * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if - * the index is out of range. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index); - -/** - * Get the game controller mapping string for a given GUID. - * - * The returned string must be freed with SDL_free(). - * - * \param guid a structure containing the GUID for which a mapping is desired. - * \returns a mapping string or NULL on error; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetDeviceGUID - * \sa SDL_JoystickGetGUID - */ -extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid); - -/** - * Get the current mapping of a Game Controller. - * - * The returned string must be freed with SDL_free(). - * - * Details about mappings are discussed with SDL_GameControllerAddMapping(). - * - * \param gamecontroller the game controller you want to get the current - * mapping for. - * \returns a string that has the controller's mapping or NULL if no mapping - * is available; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerAddMapping - * \sa SDL_GameControllerMappingForGUID - */ -extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller); - -/** - * Check if the given joystick is supported by the game controller interface. - * - * `joystick_index` is the same as the `device_index` passed to - * SDL_JoystickOpen(). - * - * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks(). - * \returns SDL_TRUE if the given joystick is supported by the game controller - * interface, SDL_FALSE if it isn't or it's an invalid index. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerNameForIndex - * \sa SDL_GameControllerOpen - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); - -/** - * Get the implementation dependent name for the game controller. - * - * This function can be called before any controllers are opened. - * - * `joystick_index` is the same as the `device_index` passed to - * SDL_JoystickOpen(). - * - * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1. - * \returns the implementation-dependent name for the game controller, or NULL - * if there is no name or the index is invalid. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerName - * \sa SDL_GameControllerOpen - * \sa SDL_IsGameController - */ -extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index); - -/** - * Get the implementation dependent path for the game controller. - * - * This function can be called before any controllers are opened. - * - * `joystick_index` is the same as the `device_index` passed to - * SDL_JoystickOpen(). - * - * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1. - * \returns the implementation-dependent path for the game controller, or NULL - * if there is no path or the index is invalid. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GameControllerPath - */ -extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_index); - -/** - * Get the type of a game controller. - * - * This can be called before any controllers are opened. - * - * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1. - * \returns the controller type. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index); - -/** - * Get the mapping of a game controller. - * - * This can be called before any controllers are opened. - * - * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1. - * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if - * no mapping is available. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index); - -/** - * Open a game controller for use. - * - * `joystick_index` is the same as the `device_index` passed to - * SDL_JoystickOpen(). - * - * The index passed as an argument refers to the N'th game controller on the - * system. This index is not the value which will identify this controller in - * future controller events. The joystick's instance id (SDL_JoystickID) will - * be used there instead. - * - * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks(). - * \returns a gamecontroller identifier or NULL if an error occurred; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerClose - * \sa SDL_GameControllerNameForIndex - * \sa SDL_IsGameController - */ -extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index); - -/** - * Get the SDL_GameController associated with an instance id. - * - * \param joyid the instance id to get the SDL_GameController for. - * \returns an SDL_GameController on success or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - */ -extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid); - -/** - * Get the SDL_GameController associated with a player index. - * - * Please note that the player index is _not_ the device index, nor is it the - * instance id! - * - * \param player_index the player index, which is not the device index or the - * instance id! - * \returns the SDL_GameController associated with a player index. - * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_GameControllerGetPlayerIndex - * \sa SDL_GameControllerSetPlayerIndex - */ -extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index); - -/** - * Get the implementation-dependent name for an opened game controller. - * - * This is the same name as returned by SDL_GameControllerNameForIndex(), but - * it takes a controller identifier instead of the (unstable) device index. - * - * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen(). - * \returns the implementation dependent name for the game controller, or NULL - * if there is no name or the identifier passed is invalid. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerNameForIndex - * \sa SDL_GameControllerOpen - */ -extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller); - -/** - * Get the implementation-dependent path for an opened game controller. - * - * This is the same path as returned by SDL_GameControllerNameForIndex(), but - * it takes a controller identifier instead of the (unstable) device index. - * - * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen(). - * \returns the implementation dependent path for the game controller, or NULL - * if there is no path or the identifier passed is invalid. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GameControllerPathForIndex - */ -extern DECLSPEC const char *SDLCALL SDL_GameControllerPath(SDL_GameController *gamecontroller); - -/** - * Get the type of this currently opened controller - * - * This is the same name as returned by SDL_GameControllerTypeForIndex(), but - * it takes a controller identifier instead of the (unstable) device index. - * - * \param gamecontroller the game controller object to query. - * \returns the controller type. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller); - -/** - * Get the player index of an opened game controller. - * - * For XInput controllers this returns the XInput user index. - * - * \param gamecontroller the game controller object to query. - * \returns the player index for controller, or -1 if it's not available. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller); - -/** - * Set the player index of an opened game controller. - * - * \param gamecontroller the game controller object to adjust. - * \param player_index Player index to assign to this controller, or -1 to - * clear the player index and turn off player LEDs. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index); - -/** - * Get the USB vendor ID of an opened controller, if available. - * - * If the vendor ID isn't available this function returns 0. - * - * \param gamecontroller the game controller object to query. - * \return the USB vendor ID, or zero if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller); - -/** - * Get the USB product ID of an opened controller, if available. - * - * If the product ID isn't available this function returns 0. - * - * \param gamecontroller the game controller object to query. - * \return the USB product ID, or zero if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller); - -/** - * Get the product version of an opened controller, if available. - * - * If the product version isn't available this function returns 0. - * - * \param gamecontroller the game controller object to query. - * \return the USB product version, or zero if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller); - -/** - * Get the firmware version of an opened controller, if available. - * - * If the firmware version isn't available this function returns 0. - * - * \param gamecontroller the game controller object to query. - * \return the controller firmware version, or zero if unavailable. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetFirmwareVersion(SDL_GameController *gamecontroller); - -/** - * Get the serial number of an opened controller, if available. - * - * Returns the serial number of the controller, or NULL if it is not - * available. - * - * \param gamecontroller the game controller object to query. - * \return the serial number, or NULL if unavailable. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller); - -/** - * Get the Steam Input handle of an opened controller, if available. - * - * Returns an InputHandle_t for the controller that can be used with Steam - * Input API: https://partner.steamgames.com/doc/api/ISteamInput - * - * \param gamecontroller the game controller object to query. - * \returns the gamepad handle, or 0 if unavailable. - * - * \since This function is available since SDL 2.30.0. - */ -extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameController *gamecontroller); - - -/** - * Check if a controller has been opened and is currently connected. - * - * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen(). - * \returns SDL_TRUE if the controller has been opened and is currently - * connected, or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerClose - * \sa SDL_GameControllerOpen - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller); - -/** - * Get the Joystick ID from a Game Controller. - * - * This function will give you a SDL_Joystick object, which allows you to use - * the SDL_Joystick functions with a SDL_GameController object. This would be - * useful for getting a joystick's position at any given time, even if it - * hasn't moved (moving it would produce an event, which would have the axis' - * value). - * - * The pointer returned is owned by the SDL_GameController. You should not - * call SDL_JoystickClose() on it, for example, since doing so will likely - * cause SDL to crash. - * - * \param gamecontroller the game controller object that you want to get a - * joystick from. - * \returns a SDL_Joystick object; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller); - -/** - * Query or change current state of Game Controller events. - * - * If controller events are disabled, you must call SDL_GameControllerUpdate() - * yourself and check the state of the controller when you want controller - * information. - * - * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0, - * and 1 will have any effect. Other numbers will just be returned. - * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. - * \returns the same value passed to the function, with exception to -1 - * (SDL_QUERY), which will return the current state. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickEventState - */ -extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state); - -/** - * Manually pump game controller updates if not using the loop. - * - * This function is called automatically by the event loop if events are - * enabled. Under such circumstances, it will not be necessary to call this - * function. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); - - -/** - * The list of axes available from a controller - * - * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to - * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though - * advanced UI will allow users to set or autodetect the dead zone, which - * varies between controllers. - * - * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully - * pressed) when reported by SDL_GameControllerGetAxis(). Note that this is - * not the same range that will be reported by the lower-level - * SDL_GetJoystickAxis(). - */ -typedef enum SDL_GameControllerAxis -{ - SDL_CONTROLLER_AXIS_INVALID = -1, - SDL_CONTROLLER_AXIS_LEFTX, - SDL_CONTROLLER_AXIS_LEFTY, - SDL_CONTROLLER_AXIS_RIGHTX, - SDL_CONTROLLER_AXIS_RIGHTY, - SDL_CONTROLLER_AXIS_TRIGGERLEFT, - SDL_CONTROLLER_AXIS_TRIGGERRIGHT, - SDL_CONTROLLER_AXIS_MAX -} SDL_GameControllerAxis; - -/** - * Convert a string into SDL_GameControllerAxis enum. - * - * This function is called internally to translate SDL_GameController mapping - * strings for the underlying joystick device into the consistent - * SDL_GameController mapping. You do not normally need to call this function - * unless you are parsing SDL_GameController mappings in your own code. - * - * Note specially that "righttrigger" and "lefttrigger" map to - * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`, - * respectively. - * - * \param str string representing a SDL_GameController axis. - * \returns the SDL_GameControllerAxis enum corresponding to the input string, - * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetStringForAxis - */ -extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str); - -/** - * Convert from an SDL_GameControllerAxis enum to a string. - * - * The caller should not SDL_free() the returned string. - * - * \param axis an enum value for a given SDL_GameControllerAxis. - * \returns a string for the given axis, or NULL if an invalid axis is - * specified. The string returned is of the format used by - * SDL_GameController mapping strings. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetAxisFromString - */ -extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis); - -/** - * Get the SDL joystick layer binding for a controller axis mapping. - * - * \param gamecontroller a game controller. - * \param axis an axis enum value (one of the SDL_GameControllerAxis values). - * \returns a SDL_GameControllerButtonBind describing the bind. On failure - * (like the given Controller axis doesn't exist on the device), its - * `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetBindForButton - */ -extern DECLSPEC SDL_GameControllerButtonBind SDLCALL -SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, - SDL_GameControllerAxis axis); - -/** - * Query whether a game controller has a given axis. - * - * This merely reports whether the controller's mapping defined this axis, as - * that is all the information SDL has about the physical device. - * - * \param gamecontroller a game controller. - * \param axis an axis enum value (an SDL_GameControllerAxis value). - * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL -SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); - -/** - * Get the current state of an axis control on a game controller. - * - * The axis indices start at index 0. - * - * For thumbsticks, the state is a value ranging from -32768 (up/left) to - * 32767 (down/right). - * - * Triggers range from 0 when released to 32767 when fully pressed, and never - * return a negative value. Note that this differs from the value reported by - * the lower-level SDL_JoystickGetAxis(), which normally uses the full range. - * - * \param gamecontroller a game controller. - * \param axis an axis index (one of the SDL_GameControllerAxis values). - * \returns axis state (including 0) on success or 0 (also) on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetButton - */ -extern DECLSPEC Sint16 SDLCALL -SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); - -/** - * The list of buttons available from a controller - */ -typedef enum SDL_GameControllerButton -{ - SDL_CONTROLLER_BUTTON_INVALID = -1, - SDL_CONTROLLER_BUTTON_A, - SDL_CONTROLLER_BUTTON_B, - SDL_CONTROLLER_BUTTON_X, - SDL_CONTROLLER_BUTTON_Y, - SDL_CONTROLLER_BUTTON_BACK, - SDL_CONTROLLER_BUTTON_GUIDE, - SDL_CONTROLLER_BUTTON_START, - SDL_CONTROLLER_BUTTON_LEFTSTICK, - SDL_CONTROLLER_BUTTON_RIGHTSTICK, - SDL_CONTROLLER_BUTTON_LEFTSHOULDER, - SDL_CONTROLLER_BUTTON_RIGHTSHOULDER, - SDL_CONTROLLER_BUTTON_DPAD_UP, - SDL_CONTROLLER_BUTTON_DPAD_DOWN, - SDL_CONTROLLER_BUTTON_DPAD_LEFT, - SDL_CONTROLLER_BUTTON_DPAD_RIGHT, - SDL_CONTROLLER_BUTTON_MISC1, /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button */ - SDL_CONTROLLER_BUTTON_PADDLE1, /* Xbox Elite paddle P1 (upper left, facing the back) */ - SDL_CONTROLLER_BUTTON_PADDLE2, /* Xbox Elite paddle P3 (upper right, facing the back) */ - SDL_CONTROLLER_BUTTON_PADDLE3, /* Xbox Elite paddle P2 (lower left, facing the back) */ - SDL_CONTROLLER_BUTTON_PADDLE4, /* Xbox Elite paddle P4 (lower right, facing the back) */ - SDL_CONTROLLER_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_CONTROLLER_BUTTON_MAX -} SDL_GameControllerButton; - -/** - * Convert a string into an SDL_GameControllerButton enum. - * - * This function is called internally to translate SDL_GameController mapping - * strings for the underlying joystick device into the consistent - * SDL_GameController mapping. You do not normally need to call this function - * unless you are parsing SDL_GameController mappings in your own code. - * - * \param str string representing a SDL_GameController axis. - * \returns the SDL_GameControllerButton enum corresponding to the input - * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str); - -/** - * Convert from an SDL_GameControllerButton enum to a string. - * - * The caller should not SDL_free() the returned string. - * - * \param button an enum value for a given SDL_GameControllerButton. - * \returns a string for the given button, or NULL if an invalid button is - * specified. The string returned is of the format used by - * SDL_GameController mapping strings. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetButtonFromString - */ -extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button); - -/** - * Get the SDL joystick layer binding for a controller button mapping. - * - * \param gamecontroller a game controller. - * \param button an button enum value (an SDL_GameControllerButton value). - * \returns a SDL_GameControllerButtonBind describing the bind. On failure - * (like the given Controller button doesn't exist on the device), - * its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetBindForAxis - */ -extern DECLSPEC SDL_GameControllerButtonBind SDLCALL -SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, - SDL_GameControllerButton button); - -/** - * Query whether a game controller has a given button. - * - * This merely reports whether the controller's mapping defined this button, - * as that is all the information SDL has about the physical device. - * - * \param gamecontroller a game controller. - * \param button a button enum value (an SDL_GameControllerButton value). - * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller, - SDL_GameControllerButton button); - -/** - * Get the current state of a button on a game controller. - * - * \param gamecontroller a game controller. - * \param button a button index (one of the SDL_GameControllerButton values). - * \returns 1 for pressed state or 0 for not pressed state or error; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerGetAxis - */ -extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller, - SDL_GameControllerButton button); - -/** - * Get the number of touchpads on a game controller. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller); - -/** - * Get the number of supported simultaneous fingers on a touchpad on a game - * controller. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad); - -/** - * Get the current state of a finger on a touchpad on a game controller. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); - -/** - * Return whether a game controller has a particular sensor. - * - * \param gamecontroller The controller to query. - * \param type The type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type); - -/** - * Set whether data reporting for a game controller sensor is enabled. - * - * \param gamecontroller The controller to update. - * \param type The type of sensor to enable/disable. - * \param enabled Whether data reporting should be enabled. - * \returns 0 or -1 if an error occurred. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled); - -/** - * Query whether sensor data reporting is enabled for a game controller. - * - * \param gamecontroller The controller to query. - * \param type The type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type); - -/** - * Get the data rate (number of events per second) of a game controller - * sensor. - * - * \param gamecontroller The controller to query. - * \param type The type of sensor to query. - * \return the data rate, or 0.0f if the data rate is not available. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameController *gamecontroller, SDL_SensorType type); - -/** - * Get the current state of a game controller sensor. - * - * The number of values and interpretation of the data is sensor dependent. - * See SDL_sensor.h for the details for each type of sensor. - * - * \param gamecontroller The controller to query. - * \param type The type of sensor to query. - * \param data A pointer filled with the current sensor state. - * \param num_values The number of values to write to data. - * \return 0 or -1 if an error occurred. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values); - -/** - * Get the current state of a game controller sensor with the timestamp of the - * last update. - * - * The number of values and interpretation of the data is sensor dependent. - * See SDL_sensor.h for the details for each type of sensor. - * - * \param gamecontroller The controller to query. - * \param type The type of sensor to query. - * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not. - * \param data A pointer filled with the current sensor state. - * \param num_values The number of values to write to data. - * \return 0 or -1 if an error occurred. - * - * \since This function is available since SDL 2.26.0. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_GameController *gamecontroller, SDL_SensorType type, Uint64 *timestamp, float *data, int num_values); - -/** - * Start a rumble effect on a game controller. - * - * Each call to this function cancels any previous rumble effect, and calling - * it with 0 intensity stops any rumbling. - * - * \param gamecontroller The controller to vibrate. - * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF. - * \param high_frequency_rumble The intensity of the high frequency (right) - * rumble motor, from 0 to 0xFFFF. - * \param duration_ms The duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if rumble isn't supported on this controller. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_GameControllerHasRumble - */ -extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); - -/** - * Start a rumble effect in the game controller's triggers. - * - * Each call to this function cancels any previous trigger rumble effect, and - * calling it with 0 intensity stops any rumbling. - * - * Note that this is rumbling of the _triggers_ and not the game controller as - * a whole. This is currently only supported on Xbox One controllers. If you - * want the (more common) whole-controller rumble, use - * SDL_GameControllerRumble() instead. - * - * \param gamecontroller The controller to vibrate. - * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF. - * \param right_rumble The intensity of the right trigger rumble motor, from 0 - * to 0xFFFF. - * \param duration_ms The duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if trigger rumble isn't supported on this controller. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_GameControllerHasRumbleTriggers - */ -extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); - -/** - * Query whether a game controller has an LED. - * - * \param gamecontroller The controller to query. - * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a - * modifiable LED. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller); - -/** - * Query whether a game controller has rumble support. - * - * \param gamecontroller The controller to query. - * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble - * support. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GameControllerRumble - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController *gamecontroller); - -/** - * Query whether a game controller has rumble support on triggers. - * - * \param gamecontroller The controller to query. - * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger - * rumble support. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GameControllerRumbleTriggers - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameController *gamecontroller); - -/** - * Update a game controller's LED color. - * - * \param gamecontroller The controller to update. - * \param red The intensity of the red LED. - * \param green The intensity of the green LED. - * \param blue The intensity of the blue LED. - * \returns 0, or -1 if this controller does not have a modifiable LED. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue); - -/** - * Send a controller specific effect packet - * - * \param gamecontroller The controller to affect. - * \param data The data to send to the controller. - * \param size The size of the data to send to the controller. - * \returns 0, or -1 if this controller or driver doesn't support effect - * packets. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size); - -/** - * Close a game controller previously opened with SDL_GameControllerOpen(). - * - * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerOpen - */ -extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller); - -/** - * Return the sfSymbolsName for a given button on a game controller on Apple - * platforms. - * - * \param gamecontroller the controller to query. - * \param button a button on the game controller. - * \returns the sfSymbolsName or NULL if the name can't be found. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GameControllerGetAppleSFSymbolsNameForAxis - */ -extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForButton(SDL_GameController *gamecontroller, SDL_GameControllerButton button); - -/** - * Return the sfSymbolsName for a given axis on a game controller on Apple - * platforms. - * - * \param gamecontroller the controller to query. - * \param axis an axis on the game controller. - * \returns the sfSymbolsName or NULL if the name can't be found. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GameControllerGetAppleSFSymbolsNameForButton - */ -extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_gamecontroller_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_gesture.h b/code/thirdparty/SDL2-2.32.8/include/SDL_gesture.h deleted file mode 100644 index acfa56f31f..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_gesture.h +++ /dev/null @@ -1,117 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryGesture - * - * Include file for SDL gesture event handling. - */ - -#ifndef SDL_gesture_h_ -#define SDL_gesture_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_video.h" - -#include "SDL_touch.h" - - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -typedef Sint64 SDL_GestureID; - -/* Function prototypes */ - -/** - * Begin recording a gesture on a specified touch device or all touch devices. - * - * If the parameter `touchId` is -1 (i.e., all devices), this function will - * always return 1, regardless of whether there actually are any devices. - * - * \param touchId the touch device id, or -1 for all touch devices. - * \returns 1 on success or 0 if the specified device could not be found. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTouchDevice - */ -extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId); - - -/** - * Save all currently loaded Dollar Gesture templates. - * - * \param dst a SDL_RWops to save to. - * \returns the number of saved templates on success or 0 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LoadDollarTemplates - * \sa SDL_SaveDollarTemplate - */ -extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst); - -/** - * Save a currently loaded Dollar Gesture template. - * - * \param gestureId a gesture id. - * \param dst a SDL_RWops to save to. - * \returns 1 on success or 0 on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LoadDollarTemplates - * \sa SDL_SaveAllDollarTemplates - */ -extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst); - - -/** - * Load Dollar Gesture templates from a file. - * - * \param touchId a touch id. - * \param src a SDL_RWops to load from. - * \returns the number of loaded templates on success or a negative error code - * (or 0) on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SaveAllDollarTemplates - * \sa SDL_SaveDollarTemplate - */ -extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_gesture_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_hidapi.h b/code/thirdparty/SDL2-2.32.8/include/SDL_hidapi.h deleted file mode 100644 index b14442a6c2..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_hidapi.h +++ /dev/null @@ -1,443 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: HIDAPI */ - -/** - * # CategoryHIDAPI - * - * Header file for SDL HIDAPI functions. - * - * This is an adaptation of the original HIDAPI interface by Alan Ott, and - * includes source code licensed under the following license: - * - * ``` - * HIDAPI - Multi-Platform library for - * communication with HID devices. - * - * Copyright 2009, Alan Ott, Signal 11 Software. - * All Rights Reserved. - * - * This software may be used by anyone for any reason so - * long as the copyright notice in the source files - * remains intact. - * ``` - * - * (Note that this license is the same as item three of SDL's zlib license, so - * it adds no new requirements on the user.) - * - * If you would like a version of SDL without this code, you can build SDL - * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for - * example on iOS or tvOS to avoid a dependency on the CoreBluetooth - * framework. - */ - -#ifndef SDL_hidapi_h_ -#define SDL_hidapi_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * A handle representing an open HID device - */ -struct SDL_hid_device_; -typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ - -/** hidapi info structure */ - -/** - * Information about a connected HID device - */ -typedef struct SDL_hid_device_info -{ - /** Platform-specific device path */ - char *path; - /** Device Vendor ID */ - unsigned short vendor_id; - /** Device Product ID */ - unsigned short product_id; - /** Serial Number */ - wchar_t *serial_number; - /** Device Release Number in binary-coded decimal, - also known as Device Version Number */ - unsigned short release_number; - /** Manufacturer String */ - wchar_t *manufacturer_string; - /** Product string */ - wchar_t *product_string; - /** Usage Page for this Device/Interface - (Windows/Mac only). */ - unsigned short usage_page; - /** Usage for this Device/Interface - (Windows/Mac only).*/ - unsigned short usage; - /** The USB interface which this logical device - represents. - - * Valid on both Linux implementations in all cases. - * Valid on the Windows implementation only if the device - contains more than one interface. */ - int interface_number; - - /** Additional information about the USB interface. - Valid on libusb and Android implementations. */ - int interface_class; - int interface_subclass; - int interface_protocol; - - /** Pointer to the next device */ - struct SDL_hid_device_info *next; -} SDL_hid_device_info; - - -/** - * Initialize the HIDAPI library. - * - * This function initializes the HIDAPI library. Calling it is not strictly - * necessary, as it will be called automatically by SDL_hid_enumerate() and - * any of the SDL_hid_open_*() functions if it is needed. This function should - * be called at the beginning of execution however, if there is a chance of - * HIDAPI handles being opened by different threads simultaneously. - * - * Each call to this function should have a matching call to SDL_hid_exit() - * - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_hid_exit - */ -extern DECLSPEC int SDLCALL SDL_hid_init(void); - -/** - * Finalize the HIDAPI library. - * - * This function frees all of the static data associated with HIDAPI. It - * should be called at the end of execution to avoid memory leaks. - * - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_hid_init - */ -extern DECLSPEC int SDLCALL SDL_hid_exit(void); - -/** - * Check to see if devices may have been added or removed. - * - * Enumerating the HID devices is an expensive operation, so you can call this - * to see if there have been any system device changes since the last call to - * this function. A change in the counter returned doesn't necessarily mean - * that anything has changed, but you can call SDL_hid_enumerate() to get an - * updated device list. - * - * Calling this function for the first time may cause a thread or other system - * resource to be allocated to track device change notifications. - * - * \returns a change counter that is incremented with each potential device - * change, or 0 if device change detection isn't available. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_hid_enumerate - */ -extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); - -/** - * Enumerate the HID Devices. - * - * This function returns a linked list of all the HID devices attached to the - * system which match vendor_id and product_id. If `vendor_id` is set to 0 - * then any vendor matches. If `product_id` is set to 0 then any product - * matches. If `vendor_id` and `product_id` are both set to 0, then all HID - * devices will be returned. - * - * \param vendor_id The Vendor ID (VID) of the types of device to open. - * \param product_id The Product ID (PID) of the types of device to open. - * \returns a pointer to a linked list of type SDL_hid_device_info, containing - * information about the HID devices attached to the system, or NULL - * in the case of failure. Free this linked list by calling - * SDL_hid_free_enumeration(). - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_hid_device_change_count - */ -extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id); - -/** - * Free an enumeration Linked List - * - * This function frees a linked list created by SDL_hid_enumerate(). - * - * \param devs Pointer to a list of struct_device returned from - * SDL_hid_enumerate(). - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); - -/** - * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally - * a serial number. - * - * If `serial_number` is NULL, the first device with the specified VID and PID - * is opened. - * - * \param vendor_id The Vendor ID (VID) of the device to open. - * \param product_id The Product ID (PID) of the device to open. - * \param serial_number The Serial Number of the device to open (Optionally - * NULL). - * \returns a pointer to a SDL_hid_device object on success or NULL on - * failure. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); - -/** - * Open a HID device by its path name. - * - * The path name be determined by calling SDL_hid_enumerate(), or a - * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). - * - * \param path The path name of the device to open. - * \returns a pointer to a SDL_hid_device object on success or NULL on - * failure. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive); - -/** - * Write an Output report to a HID device. - * - * The first byte of `data` must contain the Report ID. For devices which only - * support a single report, this must be set to 0x0. The remaining bytes - * contain the report data. Since the Report ID is mandatory, calls to - * SDL_hid_write() will always contain one more byte than the report contains. - * For example, if a hid report is 16 bytes long, 17 bytes must be passed to - * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), - * followed by the report data (16 bytes). In this example, the length passed - * in would be 17. - * - * SDL_hid_write() will send the data on the first OUT endpoint, if one - * exists. If it does not, it will send the data through the Control Endpoint - * (Endpoint 0). - * - * \param dev A device handle returned from SDL_hid_open(). - * \param data The data to send, including the report number as the first - * byte. - * \param length The length in bytes of the data to send. - * \returns the actual number of bytes written and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); - -/** - * Read an Input report from a HID device with timeout. - * - * Input reports are returned to the host through the INTERRUPT IN endpoint. - * The first byte will contain the Report number if the device uses numbered - * reports. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param data A buffer to put the read data into. - * \param length The number of bytes to read. For devices with multiple - * reports, make sure to read an extra byte for the report - * number. - * \param milliseconds timeout in milliseconds or -1 for blocking wait. - * \returns the actual number of bytes read and -1 on error. If no packet was - * available to be read within the timeout period, this function - * returns 0. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); - -/** - * Read an Input report from a HID device. - * - * Input reports are returned to the host through the INTERRUPT IN endpoint. - * The first byte will contain the Report number if the device uses numbered - * reports. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param data A buffer to put the read data into. - * \param length The number of bytes to read. For devices with multiple - * reports, make sure to read an extra byte for the report - * number. - * \returns the actual number of bytes read and -1 on error. If no packet was - * available to be read and the handle is in non-blocking mode, this - * function returns 0. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); - -/** - * Set the device handle to be non-blocking. - * - * In non-blocking mode calls to SDL_hid_read() will return immediately with a - * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read() - * will wait (block) until there is data to read before returning. - * - * Nonblocking can be turned on and off at any time. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param nonblock enable or not the nonblocking reads - 1 to enable - * nonblocking - 0 to disable nonblocking. - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); - -/** - * Send a Feature report to the device. - * - * Feature reports are sent over the Control endpoint as a Set_Report - * transfer. The first byte of `data` must contain the Report ID. For devices - * which only support a single report, this must be set to 0x0. The remaining - * bytes contain the report data. Since the Report ID is mandatory, calls to - * SDL_hid_send_feature_report() will always contain one more byte than the - * report contains. For example, if a hid report is 16 bytes long, 17 bytes - * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for - * devices which do not use numbered reports), followed by the report data (16 - * bytes). In this example, the length passed in would be 17. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param data The data to send, including the report number as the first - * byte. - * \param length The length in bytes of the data to send, including the report - * number. - * \returns the actual number of bytes written and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); - -/** - * Get a feature report from a HID device. - * - * Set the first byte of `data` to the Report ID of the report to be read. - * Make sure to allow space for this extra byte in `data`. Upon return, the - * first byte will still contain the Report ID, and the report data will start - * in data[1]. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param data A buffer to put the read data into, including the Report ID. - * Set the first byte of `data` to the Report ID of the report to - * be read, or set it to zero if your device does not use numbered - * reports. - * \param length The number of bytes to read, including an extra byte for the - * report ID. The buffer can be longer than the actual report. - * \returns the number of bytes read plus one for the report ID (which is - * still in the first byte), or -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); - -/** - * Close a HID device. - * - * \param dev A device handle returned from SDL_hid_open(). - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC void SDLCALL SDL_hid_close(SDL_hid_device *dev); - -/** - * Get The Manufacturer String from a HID device. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param string A wide string buffer to put the data into. - * \param maxlen The length of the buffer in multiples of wchar_t. - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); - -/** - * Get The Product String from a HID device. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param string A wide string buffer to put the data into. - * \param maxlen The length of the buffer in multiples of wchar_t. - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); - -/** - * Get The Serial Number String from a HID device. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param string A wide string buffer to put the data into. - * \param maxlen The length of the buffer in multiples of wchar_t. - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); - -/** - * Get a string from a HID device, based on its string index. - * - * \param dev A device handle returned from SDL_hid_open(). - * \param string_index The index of the string to get. - * \param string A wide string buffer to put the data into. - * \param maxlen The length of the buffer in multiples of wchar_t. - * \returns 0 on success and -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); - -/** - * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers - * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_hidapi_h_ */ - -/* vi: set sts=4 ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_hints.h b/code/thirdparty/SDL2-2.32.8/include/SDL_hints.h deleted file mode 100644 index 6713d01fea..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_hints.h +++ /dev/null @@ -1,3303 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryHints - * - * Official documentation for SDL configuration variables - * - * This file contains functions to set and get configuration hints, as well as - * listing each of them alphabetically. - * - * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the - * environment variable that can be used to override the default. - * - * In general these hints are just that - they may or may not be supported or - * applicable on any given platform, but they provide a way for an application - * or user to give the library a hint as to how they would like the library to - * work. - */ - -#ifndef SDL_hints_h_ -#define SDL_hints_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * A variable controlling whether the Android / iOS built-in accelerometer - * should be listed as a joystick device. - * - * This variable can be set to the following values: - * - * - "0": The accelerometer is not listed as a joystick - * - "1": The accelerometer is available as a 3 axis joystick (the default). - */ -#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK" - -/** - * Specify the behavior of Alt+Tab while the keyboard is grabbed. - * - * By default, SDL emulates Alt+Tab functionality while the keyboard is - * grabbed and your window is full-screen. This prevents the user from getting - * stuck in your application if you've enabled keyboard grab. - * - * The variable can be set to the following values: - * - * - "0": SDL will not handle Alt+Tab. Your application is responsible for - * handling Alt+Tab while the keyboard is grabbed. - * - "1": SDL will minimize your window when Alt+Tab is pressed (default) - */ -#define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" - -/** - * If set to "0" then never set the top most bit on a SDL Window, even if the - * video mode expects it. - * - * This is a debugging aid for developers and not expected to be used by end - * users. The default is "1" - * - * This variable can be set to the following values: - * - * - "0": don't allow topmost - * - "1": allow topmost - */ -#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" - -/** - * Android APK expansion main file version. - * - * Should be a string number like "1", "2" etc. - * - * Must be set together with - * SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. - * - * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and - * assets. - * - * By default this hint is not set and the APK expansion files are not - * searched. - */ -#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION" - -/** - * Android APK expansion patch file version. - * - * Should be a string number like "1", "2" etc. - * - * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION. - * - * If both hints were set then SDL_RWFromFile() will look into expansion files - * after a given relative path was not found in the internal storage and - * assets. - * - * By default this hint is not set and the APK expansion files are not - * searched. - */ -#define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION" - -/** - * A variable to control whether the event loop will block itself when the app - * is paused. - * - * The variable can be set to the following values: - * - * - "0": Non blocking. - * - "1": Blocking. (default) - * - * The value should be set before SDL is initialized. - */ -#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" - -/** - * A variable to control whether SDL will pause audio in background (Requires - * SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") - * - * The variable can be set to the following values: - * - * - "0": Non paused. - * - "1": Paused. (default) - * - * The value should be set before SDL is initialized. - */ -#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" - -/** - * A variable to control whether we trap the Android back button to handle it - * manually. - * - * This is necessary for the right mouse button to work on some Android - * devices, or to be able to trap the back button for use in your code - * reliably. If set to true, the back button will show up as an SDL_KEYDOWN / - * SDL_KEYUP pair with a keycode of SDL_SCANCODE_AC_BACK. - * - * The variable can be set to the following values: - * - * - "0": Back button will be handled as usual for system. (default) - * - "1": Back button will be trapped, allowing you to handle the key press - * manually. (This will also let right mouse click work on systems where the - * right mouse button functions as back.) - * - * The value of this hint is used at runtime, so it can be changed at any - * time. - */ -#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" - -/** - * Specify an application name. - * - * This hint lets you specify the application name sent to the OS when - * required. For example, this will often appear in volume control applets for - * audio streams, and in lists of applications which are inhibiting the - * screensaver. You should use a string that describes your program ("My Game - * 2: The Revenge") - * - * Setting this to "" or leaving it unset will have SDL use a reasonable - * default: probably the application's name or "SDL Application" if SDL - * doesn't have any better information. - * - * Note that, for audio streams, this can be overridden with - * SDL_HINT_AUDIO_DEVICE_APP_NAME. - * - * On targets where this is not supported, this hint does nothing. - */ -#define SDL_HINT_APP_NAME "SDL_APP_NAME" - -/** - * A variable controlling whether controllers used with the Apple TV generate - * UI events. - * - * When UI events are generated by controller input, the app will be - * backgrounded when the Apple TV remote's menu button is pressed, and when - * the pause or B buttons on gamepads are pressed. - * - * More information about properly making use of controllers for the Apple TV - * can be found here: - * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ - * - * This variable can be set to the following values: - * - * - "0": Controller input does not generate UI events (the default). - * - "1": Controller input generates UI events. - */ -#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" - -/** - * A variable controlling whether the Apple TV remote's joystick axes will - * automatically match the rotation of the remote. - * - * This variable can be set to the following values: - * - * - "0": Remote orientation does not affect joystick axes (the default). - * - "1": Joystick axes are based on the orientation of the remote. - */ -#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" - -/** - * A variable controlling the audio category on iOS and Mac OS X - * - * This variable can be set to the following values: - * - * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be - * muted by the phone mute switch (default) - * - "playback": Use the AVAudioSessionCategoryPlayback category - * - * For more information, see Apple's documentation: - * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html - */ -#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" - -/** - * Specify an application name for an audio device. - * - * Some audio backends (such as PulseAudio) allow you to describe your audio - * stream. Among other things, this description might show up in a system - * control panel that lets the user adjust the volume on specific audio - * streams instead of using one giant master volume slider. - * - * This hints lets you transmit that information to the OS. The contents of - * this hint are used while opening an audio device. You should use a string - * that describes your program ("My Game 2: The Revenge") - * - * Setting this to "" or leaving it unset will have SDL use a reasonable - * default: this will be the name set with SDL_HINT_APP_NAME, if that hint is - * set. Otherwise, it'll probably the application's name or "SDL Application" - * if SDL doesn't have any better information. - * - * On targets where this is not supported, this hint does nothing. - */ -#define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME" - -/** - * Specify an application name for an audio device. - * - * Some audio backends (such as PulseAudio) allow you to describe your audio - * stream. Among other things, this description might show up in a system - * control panel that lets the user adjust the volume on specific audio - * streams instead of using one giant master volume slider. - * - * This hints lets you transmit that information to the OS. The contents of - * this hint are used while opening an audio device. You should use a string - * that describes your what your program is playing ("audio stream" is - * probably sufficient in many cases, but this could be useful for something - * like "team chat" if you have a headset playing VoIP audio separately). - * - * Setting this to "" or leaving it unset will have SDL use a reasonable - * default: "audio stream" or something similar. - * - * On targets where this is not supported, this hint does nothing. - */ -#define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" - -/** - * Specify an application role for an audio device. - * - * Some audio backends (such as Pipewire) allow you to describe the role of - * your audio stream. Among other things, this description might show up in a - * system control panel or software for displaying and manipulating media - * playback/capture graphs. - * - * This hints lets you transmit that information to the OS. The contents of - * this hint are used while opening an audio device. You should use a string - * that describes your what your program is playing (Game, Music, Movie, - * etc...). - * - * Setting this to "" or leaving it unset will have SDL use a reasonable - * default: "Game" or something similar. - * - * On targets where this is not supported, this hint does nothing. - */ -#define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" - -/** - * A variable controlling speed/quality tradeoff of audio resampling. - * - * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) - * to handle audio resampling. There are different resampling modes available - * that produce different levels of quality, using more CPU. - * - * If this hint isn't specified to a valid setting, or libsamplerate isn't - * available, SDL will use the default, internal resampling algorithm. - * - * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is - * available. - * - * This hint is currently only checked at audio subsystem initialization. - * - * This variable can be set to the following values: - * - * - "0" or "default": Use SDL's internal resampling (Default when not set - - * low quality, fast) - * - "1" or "fast": Use fast, slightly higher quality resampling, if available - * - "2" or "medium": Use medium quality resampling, if available - * - "3" or "best": Use high quality resampling, if available - */ -#define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE" - -/** - * A variable controlling whether SDL updates joystick state when getting - * input events - * - * This variable can be set to the following values: - * - * - "0": You'll call SDL_JoystickUpdate() manually - * - "1": SDL will automatically call SDL_JoystickUpdate() (default) - * - * This hint can be toggled on and off at runtime. - */ -#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" - -/** - * A variable controlling whether SDL updates sensor state when getting input - * events - * - * This variable can be set to the following values: - * - * - "0": You'll call SDL_SensorUpdate() manually - * - "1": SDL will automatically call SDL_SensorUpdate() (default) - * - * This hint can be toggled on and off at runtime. - */ -#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" - -/** - * Prevent SDL from using version 4 of the bitmap header when saving BMPs. - * - * The bitmap header version 4 is required for proper alpha channel support - * and SDL will use it when required. Should this not be desired, this hint - * can force the use of the 40 byte header version which is supported - * everywhere. - * - * The variable can be set to the following values: - * - * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit - * BMP file with an alpha mask. SDL will use the bitmap header version 4 and - * set the alpha mask accordingly. - * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit - * BMP file without an alpha mask. The alpha channel data will be in the - * file, but applications are going to ignore it. - * - * The default value is "0". - */ -#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" - -/** - * Override for SDL_GetDisplayUsableBounds() - * - * If set, this hint will override the expected results for - * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want - * to do this, but this allows an embedded system to request that some of the - * screen be reserved for other uses when paired with a well-behaved - * application. - * - * The contents of this hint must be 4 comma-separated integers, the first is - * the bounds x, then y, width and height, in that order. - */ -#define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" - -/** - * Disable giving back control to the browser automatically when running with - * asyncify - * - * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations such as - * refreshing the screen or polling events. - * - * This hint only applies to the emscripten platform - * - * The variable can be set to the following values: - * - * - "0": Disable emscripten_sleep calls (if you give back browser control - * manually or use asyncify for other purposes) - * - "1": Enable emscripten_sleep calls (the default) - */ -#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" - -/** - * override the binding element for keyboard inputs for Emscripten builds - * - * This hint only applies to the emscripten platform. - * - * The variable can be one of: - * - * - "#window": the javascript window object (this is the default) - * - "#document": the javascript document object - * - "#screen": the javascript window.screen object - * - "#canvas": the WebGL canvas element - * - * Any other string without a leading # sign applies to the element on the - * page with that ID. - */ -#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" - -/** - * A variable that controls whether the on-screen keyboard should be shown - * when text input is active - * - * The variable can be set to the following values: - * - * - "0": Do not show the on-screen keyboard - * - "1": Show the on-screen keyboard - * - * The default value is "1". This hint must be set before text input is - * activated. - */ -#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" - -/** - * A variable controlling verbosity of the logging of SDL events pushed onto - * the internal queue. - * - * This variable can be set to the following values, from least to most - * verbose: - * - * - "0": Don't log any events (default) - * - "1": Log most events (other than the really spammy ones). - * - "2": Include mouse and finger motion events. - * - "3": Include SDL_SysWMEvent events. - * - * This is generally meant to be used to debug SDL itself, but can be useful - * for application developers that need better visibility into what is going - * on in the event queue. Logged events are sent through SDL_Log(), which - * means by default they appear on stdout on most platforms or maybe - * OutputDebugString() on Windows, and can be funneled by the app with - * SDL_LogSetOutputFunction(), etc. - * - * This hint can be toggled on and off at runtime, if you only need to log - * events for a small subset of program execution. - */ -#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" - -/** - * A variable controlling whether raising the window should be done more - * forcefully - * - * This variable can be set to the following values: - * - * - "0": No forcing (the default) - * - "1": Extra level of forcing - * - * At present, this is only an issue under MS Windows, which makes it nearly - * impossible to programmatically move a window to the foreground, for - * "security" reasons. See http://stackoverflow.com/a/34414846 for a - * discussion. - */ -#define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW" - -/** - * A variable controlling how 3D acceleration is used to accelerate the SDL - * screen surface. - * - * SDL can try to accelerate the SDL screen surface by using streaming - * textures with a 3D rendering engine. This variable controls whether and how - * this is done. - * - * This variable can be set to the following values: - * - * - "0": Disable 3D acceleration - * - "1": Enable 3D acceleration, using the default renderer. - * - "X": Enable 3D acceleration, using X where X is one of the valid - * rendering drivers. (e.g. "direct3d", "opengl", etc.) - * - * By default SDL tries to make a best guess for each platform whether to use - * acceleration or not. - */ -#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" - -/** - * A variable that lets you manually hint extra gamecontroller db entries. - * - * The variable should be newline delimited rows of gamecontroller config - * data, see SDL_gamecontroller.h - * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You - * can update mappings after the system is initialized with - * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() - */ -#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" - -/** - * A variable that lets you provide a file with extra gamecontroller db - * entries. - * - * The file should contain lines of gamecontroller config data, see - * SDL_gamecontroller.h - * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You - * can update mappings after the system is initialized with - * SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() - */ -#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" - -/** - * A variable that overrides the automatic controller type detection - * - * The variable should be comma separated entries, in the form: VID/PID=type - * - * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd - * - * The type should be one of: Xbox360 XboxOne PS3 PS4 PS5 SwitchPro - * - * This hint affects what driver is used, and must be set before calling - * SDL_Init(SDL_INIT_GAMECONTROLLER) - */ -#define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" - -/** - * A variable containing a list of devices to skip when scanning for game - * controllers. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" - -/** - * If set, all devices will be skipped when scanning for game controllers - * except for the ones listed in this variable. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" - -/** - * If set, game controller face buttons report their values according to their - * labels instead of their positional layout. - * - * For example, on Nintendo Switch controllers, normally you'd get: - * - * ``` - * (Y) - * (X) (B) - * (A) - * ``` - * - * but if this hint is set, you'll get: - * - * ``` - * (X) - * (Y) (A) - * (B) - * ``` - * - * The variable can be set to the following values: - * - * - "0": Report the face buttons by position, as though they were on an Xbox - * controller. - * - "1": Report the face buttons by label instead of position - * - * The default value is "1". This hint may be set at any time. - */ -#define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" - -/** - * A variable controlling whether grabbing input grabs the keyboard - * - * This variable can be set to the following values: - * - * - "0": Grab will affect only the mouse - * - "1": Grab will affect mouse and keyboard - * - * By default SDL will not grab the keyboard so system shortcuts still work. - */ -#define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" - -/** - * A variable containing a list of devices to ignore in SDL_hid_enumerate() - * - * For example, to ignore the Shanwan DS3 controller and any Valve controller, - * you might have the string "0x2563/0x0523,0x28de/0x0000" - */ -#define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" - -/** - * A variable controlling whether the idle timer is disabled on iOS. - * - * When an iOS app does not receive touches for some time, the screen is - * dimmed automatically. For games where the accelerometer is the only input - * this is problematic. This functionality can be disabled by setting this - * hint. - * - * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() - * accomplish the same thing on iOS. They should be preferred over this hint. - * - * This variable can be set to the following values: - * - * - "0": Enable idle timer - * - "1": Disable idle timer - */ -#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" - -/** - * A variable to control whether certain IMEs should handle text editing - * internally instead of sending SDL_TEXTEDITING events. - * - * The variable can be set to the following values: - * - * - "0": SDL_TEXTEDITING events are sent, and it is the application's - * responsibility to render the text from these events and differentiate it - * somehow from committed text. (default) - * - "1": If supported by the IME then SDL_TEXTEDITING events are not sent, - * and text that is being composed will be rendered in its own UI. - */ -#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" - -/** - * A variable to control whether certain IMEs should show native UI components - * (such as the Candidate List) instead of suppressing them. - * - * The variable can be set to the following values: - * - * - "0": Native UI components are not display. (default) - * - "1": Native UI components are displayed. - */ -#define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" - -/** - * A variable to control if extended IME text support is enabled. - * - * If enabled then SDL_TextEditingExtEvent will be issued if the text would be - * truncated otherwise. Additionally SDL_TextInputEvent will be dispatched - * multiple times so that it is not truncated. - * - * The variable can be set to the following values: - * - * - "0": Legacy behavior. Text can be truncated, no heap allocations. - * (default) - * - "1": Modern behavior. - */ -#define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT" - -/** - * A variable controlling whether the home indicator bar on iPhone X should be - * hidden. - * - * This variable can be set to the following values: - * - * - "0": The indicator bar is not hidden (default for windowed applications) - * - "1": The indicator bar is hidden and is shown when the screen is touched - * (useful for movie playback applications) - * - "2": The indicator bar is dim and the first swipe makes it visible and - * the second swipe performs the "home" action (default for fullscreen - * applications) - */ -#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" - -/** - * A variable that lets you enable joystick (and gamecontroller) events even - * when your app is in the background. - * - * The variable can be set to the following values: - * - * - "0": Disable joystick & gamecontroller input events when the application - * is in the background. - * - "1": Enable joystick & gamecontroller input events when the application - * is in the background. - * - * The default value is "0". This hint may be set at any time. - */ -#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" - -/** - * A variable containing a list of arcade stick style controllers. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" - -/** - * A variable containing a list of devices that are not arcade stick style - * controllers. - * - * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in - * device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" - -/** - * A variable containing a list of devices that should not be considerd - * joysticks. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" - -/** - * A variable containing a list of devices that should be considered - * joysticks. - * - * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in - * device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" - -/** - * A variable containing a list of flightstick style controllers. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" - -/** - * A variable containing a list of devices that are not flightstick style - * controllers. - * - * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in - * device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" - -/** - * A variable containing a list of devices known to have a GameCube form - * factor. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" - -/** - * A variable containing a list of devices known not to have a GameCube form - * factor. - * - * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in - * device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" - -/** - * A variable controlling whether the HIDAPI joystick drivers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI drivers are not used - * - "1": HIDAPI drivers are used (the default) - * - * This variable is the default for all drivers, but can be overridden by the - * hints for specific drivers below. - */ -#define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" - -/** - * A variable controlling whether the HIDAPI driver for Nintendo GameCube - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" - -/** - * A variable controlling whether "low_frequency_rumble" and - * "high_frequency_rumble" is used to implement the GameCube controller's 3 - * rumble modes, Stop(0), Rumble(1), and StopHard(2) this is useful for - * applications that need full compatibility for things like ADSR envelopes. - * - * Stop is implemented by setting "low_frequency_rumble" to "0" and - * "high_frequency_rumble" ">0" Rumble is both at any arbitrary value, - * StopHard is implemented by setting both "low_frequency_rumble" and - * "high_frequency_rumble" to "0" - * - * This variable can be set to the following values: - * - * - "0": Normal rumble behavior is behavior is used (default) - * - "1": Proper GameCube controller rumble behavior is used - */ -#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE" - -/** - * A variable controlling whether the HIDAPI driver for Nintendo Switch - * Joy-Cons should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" - -/** - * A variable controlling whether Nintendo Switch Joy-Con controllers will be - * combined into a single Pro-like controller when using the HIDAPI driver - * - * This variable can be set to the following values: - * - * - "0": Left and right Joy-Con controllers will not be combined and each - * will be a mini-gamepad - * - "1": Left and right Joy-Con controllers will be combined into a single - * controller (the default) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" - -/** - * A variable controlling whether Nintendo Switch Joy-Con controllers will be - * in vertical mode when using the HIDAPI driver - * - * This variable can be set to the following values: - * - * - "0": Left and right Joy-Con controllers will not be in vertical mode (the - * default) - * - "1": Left and right Joy-Con controllers will be in vertical mode - * - * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" - -/** - * A variable controlling whether the HIDAPI driver for Amazon Luna - * controllers connected via Bluetooth should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" - -/** - * A variable controlling whether the HIDAPI driver for Nintendo Online - * classic controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" - -/** - * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" - -/** - * A variable controlling whether the HIDAPI driver for PS3 controllers should - * be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on - * other platforms. - * - * It is not possible to use this driver on Windows, due to limitations in the - * default drivers installed. See https://github.com/ViGEm/DsHidMini for an - * alternative driver on Windows. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" - -/** - * A variable controlling whether the HIDAPI driver for PS4 controllers should - * be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" - -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * This variable can be set to the following values: - * - * - "0": extended reports are not enabled (the default) - * - "1": extended reports - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - -/** - * A variable controlling whether the HIDAPI driver for PS5 controllers should - * be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" - -/** - * A variable controlling whether the player LEDs should be lit to indicate - * which player is associated with a PS5 controller. - * - * This variable can be set to the following values: - * - * - "0": player LEDs are not enabled - * - "1": player LEDs are enabled (the default) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" - -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * This variable can be set to the following values: - * - * - "0": extended reports are not enabled (the default) - * - "1": extended reports - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - -/** - * A variable controlling whether the HIDAPI driver for Google Stadia - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" - -/** - * A variable controlling whether the HIDAPI driver for Bluetooth Steam - * Controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used for Steam Controllers, which requires - * Bluetooth access and may prompt the user for permission on iOS and - * Android. - * - * The default is "0" - */ -#define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" - -/** - * A variable controlling whether the HIDAPI driver for the Steam Deck builtin - * controller should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" - -/** - * A variable controlling whether the HIDAPI driver for Nintendo Switch - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" - -/** - * A variable controlling whether the Home button LED should be turned on when - * a Nintendo Switch Pro controller is opened - * - * This variable can be set to the following values: - * - * - "0": home button LED is turned off - * - "1": home button LED is turned on - * - * By default the Home button LED state is not changed. This hint can also be - * set to a floating point value between 0.0 and 1.0 which controls the - * brightness of the Home button LED. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" - -/** - * A variable controlling whether the Home button LED should be turned on when - * a Nintendo Switch Joy-Con controller is opened - * - * This variable can be set to the following values: - * - * - "0": home button LED is turned off - * - "1": home button LED is turned on - * - * By default the Home button LED state is not changed. This hint can also be - * set to a floating point value between 0.0 and 1.0 which controls the - * brightness of the Home button LED. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" - -/** - * A variable controlling whether the player LEDs should be lit to indicate - * which player is associated with a Nintendo Switch controller. - * - * This variable can be set to the following values: - * - * - "0": player LEDs are not enabled - * - "1": player LEDs are enabled (the default) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" - -/** - * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" - -/** - * A variable controlling whether the player LEDs should be lit to indicate - * which player is associated with a Wii controller. - * - * This variable can be set to the following values: - * - * - "0": player LEDs are not enabled - * - "1": player LEDs are enabled (the default) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" - -/** - * A variable controlling whether the HIDAPI driver for XBox controllers - * should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is "0" on Windows, otherwise the value of - * SDL_HINT_JOYSTICK_HIDAPI - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" - -/** - * A variable controlling whether the HIDAPI driver for XBox 360 controllers - * should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" - -/** - * A variable controlling whether the player LEDs should be lit to indicate - * which player is associated with an Xbox 360 controller. - * - * This variable can be set to the following values: - * - * - "0": player LEDs are not enabled - * - "1": player LEDs are enabled (the default) - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" - -/** - * A variable controlling whether the HIDAPI driver for XBox 360 wireless - * controllers should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" - -/** - * A variable controlling whether the HIDAPI driver for XBox One controllers - * should be used. - * - * This variable can be set to the following values: - * - * - "0": HIDAPI driver is not used - * - "1": HIDAPI driver is used - * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" - -/** - * A variable controlling whether the Home button LED should be turned on when - * an Xbox One controller is opened - * - * This variable can be set to the following values: - * - * - "0": home button LED is turned off - * - "1": home button LED is turned on - * - * By default the Home button LED state is not changed. This hint can also be - * set to a floating point value between 0.0 and 1.0 which controls the - * brightness of the Home button LED. The default brightness is 0.4. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" - -/** - * A variable controlling whether IOKit should be used for controller - * handling. - * - * This variable can be set to the following values: - * - * - "0": IOKit is not used - * - "1": IOKit is used (the default) - */ -#define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" - -/** - * A variable controlling whether GCController should be used for controller - * handling. - * - * This variable can be set to the following values: - * - * - "0": GCController is not used - * - "1": GCController is used (the default) - */ -#define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" - -/** - * A variable controlling whether the RAWINPUT joystick drivers should be used - * for better handling XInput-capable devices. - * - * This variable can be set to the following values: - * - * - "0": RAWINPUT drivers are not used - * - "1": RAWINPUT drivers are used (the default) - */ -#define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" - -/** - * A variable controlling whether the RAWINPUT driver should pull correlated - * data from XInput. - * - * This variable can be set to the following values: - * - * - "0": RAWINPUT driver will only use data from raw input APIs - * - "1": RAWINPUT driver will also pull data from XInput, providing better - * trigger axes, guide button presses, and rumble support for Xbox - * controllers - * - * The default is "1". This hint applies to any joysticks opened after setting - * the hint. - */ -#define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" - -/** - * A variable controlling whether the ROG Chakram mice should show up as - * joysticks - * - * This variable can be set to the following values: - * - * - "0": ROG Chakram mice do not show up as joysticks (the default) - * - "1": ROG Chakram mice show up as joysticks - */ -#define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" - -/** - * A variable controlling whether a separate thread should be used for - * handling joystick detection and raw input messages on Windows - * - * This variable can be set to the following values: - * - * - "0": A separate thread is not used (the default) - * - "1": A separate thread is used for handling raw input messages - */ -#define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" - -/** - * A variable containing a list of throttle style controllers. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" - -/** - * A variable containing a list of devices that are not throttle style - * controllers. - * - * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in - * device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" - -/** - * A variable controlling whether Windows.Gaming.Input should be used for - * controller handling. - * - * This variable can be set to the following values: - * - * - "0": WGI is not used - * - "1": WGI is used (the default) - */ -#define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" - -/** - * A variable containing a list of wheel style controllers. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" - -/** - * A variable containing a list of devices that are not wheel style - * controllers. - * - * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device - * list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" - -/** - * A variable containing a list of devices known to have all axes centered at - * zero. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" - -/** - * Determines whether SDL enforces that DRM master is required in order to - * initialize the KMSDRM video backend. - * - * The DRM subsystem has a concept of a "DRM master" which is a DRM client - * that has the ability to set planes, set cursor, etc. When SDL is DRM - * master, it can draw to the screen using the SDL rendering APIs. Without DRM - * master, SDL is still able to process input and query attributes of attached - * displays, but it cannot change display state or draw to the screen - * directly. - * - * In some cases, it can be useful to have the KMSDRM backend even if it - * cannot be used for rendering. An app may want to use SDL for input - * processing while using another rendering API (such as an MMAL overlay on - * Raspberry Pi) or using its own code to render to DRM overlays that SDL - * doesn't support. - * - * This hint must be set before initializing the video subsystem. - * - * This variable can be set to the following values: - * - * - "0": SDL will allow usage of the KMSDRM backend without DRM master - * - "1": SDL Will require DRM master to use the KMSDRM backend (default) - */ -#define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" - -/** - * A comma separated list of devices to open as joysticks - * - * This variable is currently only used by the Linux joystick driver. - */ -#define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" - - -/** - * A variable containing a list of devices and their desired number of haptic - * (force feedback) enabled axis. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form plus the number of desired axes, e.g. - * - * `0xAAAA/0xBBBB/1,0xCCCC/0xDDDD/3` - * - * This hint supports a "wildcard" device that will set the number of haptic - * axes on all initialized haptic devices which were not defined explicitly in - * this hint. - * - * `0xFFFF/0xFFFF/1` - * - * This hint should be set before a controller is opened. The number of haptic - * axes won't exceed the number of real axes found on the device. - */ -#define SDL_HINT_JOYSTICK_HAPTIC_AXES "SDL_JOYSTICK_HAPTIC_AXES" - -/** - * A variable controlling whether joysticks on Linux will always treat 'hat' - * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking - * whether they may be analog. - * - * This variable can be set to the following values: - * - * - "0": Only map hat axis inputs to digital hat outputs if the input axes - * appear to actually be digital (the default) - * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as - * digital hats - */ -#define SDL_HINT_LINUX_DIGITAL_HATS "SDL_LINUX_DIGITAL_HATS" - -/** - * A variable controlling whether digital hats on Linux will apply deadzones - * to their underlying input axes or use unfiltered values. - * - * This variable can be set to the following values: - * - * - "0": Return digital hat values based on unfiltered input axis values - * - "1": Return digital hat values with deadzones on the input axes taken - * into account (the default) - */ -#define SDL_HINT_LINUX_HAT_DEADZONES "SDL_LINUX_HAT_DEADZONES" - -/** - * A variable controlling whether to use the classic /dev/input/js* joystick - * interface or the newer /dev/input/event* joystick interface on Linux - * - * This variable can be set to the following values: - * - * - "0": Use /dev/input/event* - * - "1": Use /dev/input/js* - * - * By default the /dev/input/event* interfaces are used - */ -#define SDL_HINT_LINUX_JOYSTICK_CLASSIC "SDL_LINUX_JOYSTICK_CLASSIC" - -/** - * A variable controlling whether joysticks on Linux adhere to their - * HID-defined deadzones or return unfiltered values. - * - * This variable can be set to the following values: - * - * - "0": Return unfiltered joystick axis values (the default) - * - "1": Return axis values with deadzones taken into account - */ -#define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES" - -/** - * A variable controlling the default SDL log levels. - * - * This variable is a comma separated set of category=level tokens that define - * the default logging levels for SDL applications. - * - * The category can be a numeric category, one of "app", "error", "assert", - * "system", "audio", "video", "render", "input", "test", or `*` for any - * unspecified category. - * - * The level can be a numeric level, one of "verbose", "debug", "info", - * "warn", "error", "critical", or "quiet" to disable that category. - * - * You can omit the category if you want to set the logging level for all - * categories. - * - * If this hint isn't set, the default log levels are equivalent to: - * "app=info,assert=warn,test=verbose,*=error" - */ -#define SDL_HINT_LOGGING "SDL_LOGGING" - -/** - * When set don't force the SDL app to become a foreground process - * - * This hint only applies to Mac OS X. - */ -#define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" - -/** - * A variable that determines whether ctrl+click should generate a right-click - * event on Mac - * - * If present, holding ctrl while left clicking will generate a right click - * event when on Mac. - */ -#define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" - -/** - * A variable controlling whether dispatching OpenGL context updates should - * block the dispatching thread until the main thread finishes processing - * - * This variable can be set to the following values: - * - * - "0": Dispatching OpenGL context updates will block the dispatching thread - * until the main thread finishes processing (default). - * - "1": Dispatching OpenGL context updates will allow the dispatching thread - * to continue execution. - * - * Generally you want the default, but if you have OpenGL code in a background - * thread on a Mac, and the main thread hangs because it's waiting for that - * background thread, but that background thread is also hanging because it's - * waiting for the main thread to do an update, this might fix your issue. - * - * This hint only applies to macOS. - * - * This hint is available since SDL 2.24.0. - */ -#define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" - -/** - * A variable setting the double click radius, in pixels. - */ -#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" - -/** - * A variable setting the double click time, in milliseconds. - */ -#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" - -/** - * Allow mouse click events when clicking to focus an SDL window - * - * This variable can be set to the following values: - * - * - "0": Ignore mouse clicks that activate a window - * - "1": Generate events for mouse clicks that activate a window - * - * By default SDL will ignore mouse clicks that activate a window - */ -#define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" - -/** - * A variable setting the speed scale for mouse motion, in floating point, - * when the mouse is not in relative mode - */ -#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" - -/** - * A variable controlling whether relative mouse mode constrains the mouse to - * the center of the window - * - * This variable can be set to the following values: - * - * - "0": Relative mouse mode constrains the mouse to the window - * - "1": Relative mouse mode constrains the mouse to the center of the window - * - * Constraining to the center of the window works better for FPS games and - * when the application is running over RDP. Constraining to the whole window - * works better for 2D games and increases the chance that the mouse will be - * in the correct position when using high DPI mice. - * - * By default SDL will constrain the mouse to the center of the window - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" - -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping - * - * This variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input - * - "1": Relative mouse mode uses mouse warping - * - * By default SDL will use raw input for relative mouse mode - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - -/** - * A variable controlling whether relative mouse motion is affected by - * renderer scaling - * - * This variable can be set to the following values: - * - * - "0": Relative motion is unaffected by DPI or renderer's logical size - * - "1": Relative motion is scaled according to DPI scaling and logical size - * - * By default relative mouse deltas are affected by DPI and renderer scaling - */ -#define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING" - -/** - * A variable setting the scale for mouse motion, in floating point, when the - * mouse is in relative mode - */ -#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" - -/** - * A variable controlling whether the system mouse acceleration curve is used - * for relative mouse motion. - * - * This variable can be set to the following values: - * - * - "0": Relative mouse motion will be unscaled (the default) - * - "1": Relative mouse motion will be scaled using the system mouse - * acceleration curve. - * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the - * system speed scale. - */ -#define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" - -/** - * A variable controlling whether a motion event should be generated for mouse - * warping in relative mode. - * - * This variable can be set to the following values: - * - * - "0": Warping the mouse will not generate a motion event in relative mode - * - "1": Warping the mouse will generate a motion event in relative mode - * - * By default warping the mouse will not generate motion events in relative - * mode. This avoids the application having to filter out large relative - * motion due to warping. - */ -#define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" - -/** - * A variable controlling whether the hardware cursor stays visible when - * relative mode is active. - * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active - * - * Note that for systems without raw hardware inputs, relative mode is - * implemented using warping, so the hardware cursor will visibly warp between - * frames if this is enabled on those systems. - */ -#define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" - -/** - * A variable controlling whether mouse events should generate synthetic touch - * events - * - * This variable can be set to the following values: - * - * - "0": Mouse events will not generate touch events (default for desktop - * platforms) - * - "1": Mouse events will generate touch events (default for mobile - * platforms, such as Android and iOS) - */ -#define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" - -/** - * A variable controlling whether the mouse is captured while mouse buttons - * are pressed - * - * This variable can be set to the following values: - * - * - "0": The mouse is not captured while mouse buttons are pressed - * - "1": The mouse is captured while mouse buttons are pressed - * - * By default the mouse is captured while mouse buttons are pressed so if the - * mouse is dragged outside the window, the application continues to receive - * mouse events until the button is released. - */ -#define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" - -/** - * Tell SDL not to catch the SIGINT or SIGTERM signals. - * - * This hint only applies to Unix-like platforms, and should set before any - * calls to SDL_Init() - * - * The variable can be set to the following values: - * - * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a - * signal, convert it into an SDL_QUIT event. - * - "1": SDL will not install a signal handler at all. - */ -#define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" - -/** - * A variable controlling what driver to use for OpenGL ES contexts. - * - * On some platforms, currently Windows and X11, OpenGL drivers may support - * creating contexts with an OpenGL ES profile. By default SDL uses these - * profiles, when available, otherwise it attempts to load an OpenGL ES - * library, e.g. that provided by the ANGLE project. This variable controls - * whether SDL follows this default behaviour or will always load an OpenGL ES - * library. - * - * Circumstances where this is useful include - Testing an app with a - * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those - * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses - * at link time by linking with the OpenGL ES library instead of querying them - * at run time with SDL_GL_GetProcAddress(). - * - * Caution: for an application to work with the default behaviour across - * different OpenGL drivers it must query the OpenGL ES function addresses at - * run time using SDL_GL_GetProcAddress(). - * - * This variable is ignored on most platforms because OpenGL ES is native or - * not supported. - * - * This variable can be set to the following values: - * - * - "0": Use ES profile of OpenGL, if available. (Default when not set.) - * - "1": Load OpenGL ES library using the default library names. - */ -#define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" - -/** - * A variable controlling which orientations are allowed on iOS/Android. - * - * In some circumstances it is necessary to be able to explicitly control - * which UI orientations are allowed. - * - * This variable is a space delimited list of the following values: - * - * - "LandscapeLeft" - * - "LandscapeRight" - * - "Portrait" - * - "PortraitUpsideDown" - */ -#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" - -/** - * A variable controlling the use of a sentinel event when polling the event - * queue - * - * This variable can be set to the following values: - * - * - "0": Disable poll sentinels - * - "1": Enable poll sentinels - * - * When polling for events, SDL_PumpEvents is used to gather new events from - * devices. If a device keeps producing new events between calls to - * SDL_PumpEvents, a poll loop will become stuck until the new events stop. - * This is most noticeable when moving a high frequency mouse. - * - * By default, poll sentinels are enabled. - */ -#define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" - -/** - * Override for SDL_GetPreferredLocales() - * - * If set, this will be favored over anything the OS might report for the - * user's preferred locales. Changing this hint at runtime will not generate a - * SDL_LOCALECHANGED event (but if you can change the hint, you can push your - * own event, if you want). - * - * The format of this hint is a comma-separated list of language and locale, - * combined with an underscore, as is a common format: "en_GB". Locale is - * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" - */ -#define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" - -/** - * A variable describing the content orientation on QtWayland-based platforms. - * - * On QtWayland platforms, windows are rotated client-side to allow for custom - * transitions. In order to correctly position overlays (e.g. volume bar) and - * gestures (e.g. events view, close/minimize gestures), the system needs to - * know in which orientation the application is currently drawing its - * contents. - * - * This does not cause the window to be rotated or resized, the application - * needs to take care of drawing the content in the right orientation (the - * framebuffer is always in portrait mode). - * - * This variable can be one of the following values: - * - * - "primary" (default) - * - "portrait" - * - "landscape" - * - "inverted-portrait" - * - "inverted-landscape" - * - * Since SDL 2.0.22 this variable accepts a comma-separated list of values - * above. - */ -#define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION" - -/** - * Flags to set on QtWayland windows to integrate with the native window - * manager. - * - * On QtWayland platforms, this hint controls the flags to set on the windows. - * For example, on Sailfish OS "OverridesSystemGestures" disables swipe - * gestures. - * - * This variable is a space-separated list of the following values (empty = no - * flags): - * - * - "OverridesSystemGestures" - * - "StaysOnTop" - * - "BypassWindowManager" - */ -#define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS" - -/** - * A variable controlling whether the 2D render API is compatible or - * efficient. - * - * This variable can be set to the following values: - * - * - "0": Don't use batching to make rendering more efficient. - * - "1": Use batching, but might cause problems if app makes its own direct - * OpenGL calls. - * - * Up to SDL 2.0.9, the render API would draw immediately when requested. Now - * it batches up draw requests and sends them all to the GPU only when forced - * to (during SDL_RenderPresent, when changing render targets, by updating a - * texture that the batch needs, etc). This is significantly more efficient, - * but it can cause problems for apps that expect to render on top of the - * render API's output. As such, SDL will disable batching if a specific - * render backend is requested (since this might indicate that the app is - * planning to use the underlying graphics API directly). This hint can be - * used to explicitly request batching in this instance. It is a contract that - * you will either never use the underlying graphics API directly, or if you - * do, you will call SDL_RenderFlush() before you do so any current batch goes - * to the GPU before your work begins. Not following this contract will result - * in undefined behavior. - */ -#define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING" - -/** - * A variable controlling how the 2D render API renders lines - * - * This variable can be set to the following values: - * - * - "0": Use the default line drawing method (Bresenham's line algorithm as - * of SDL 2.0.20) - * - "1": Use the driver point API using Bresenham's line algorithm (correct, - * draws many points) - * - "2": Use the driver line API (occasionally misses line endpoints based on - * hardware driver quirks, was the default before 2.0.20) - * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) - * - * This variable should be set when the renderer is created. - */ -#define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" - -/** - * A variable controlling whether to enable Direct3D 11+'s Debug Layer. - * - * This variable does not have any effect on the Direct3D 9 based renderer. - * - * This variable can be set to the following values: - * - * - "0": Disable Debug Layer use - * - "1": Enable Debug Layer use - * - * By default, SDL does not use Direct3D Debug Layer. - */ -#define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" - -/** - * A variable controlling whether the Direct3D device is initialized for - * thread-safe operations. - * - * This variable can be set to the following values: - * - * - "0": Thread-safety is not enabled (faster) - * - "1": Thread-safety is enabled - * - * By default the Direct3D device is created with thread-safety disabled. - */ -#define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" - -/** - * A variable specifying which render driver to use. - * - * If the application doesn't pick a specific renderer to use, this variable - * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. - * - * This variable is case insensitive and can be set to the following values: - * - * - "direct3d" - * - "direct3d11" - * - "direct3d12" - * - "opengl" - * - "opengles2" - * - "opengles" - * - "metal" - * - "software" - * - * The default varies by platform, but it's the first one in the list that is - * available on the current platform. - */ -#define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" - -/** - * A variable controlling the scaling policy for SDL_RenderSetLogicalSize. - * - * This variable can be set to the following values: - * - * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on - * screen "1" or "overscan" - Will zoom the rendering so it fills the entire - * screen, allowing edges to be drawn offscreen - * - * By default letterbox is used - */ -#define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE" - -/** - * A variable controlling whether the OpenGL render driver uses shaders if - * they are available. - * - * This variable can be set to the following values: - * - * - "0": Disable shaders - * - "1": Enable shaders - * - * By default shaders are used if OpenGL supports them. - */ -#define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" - -/** - * A variable controlling the scaling quality - * - * This variable can be set to the following values: - * - * - "0" or "nearest": Nearest pixel sampling - * - "1" or "linear": Linear filtering (supported by OpenGL and Direct3D) - * - "2" or "best": Currently this is the same as "linear" - * - * By default nearest pixel sampling is used - */ -#define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" - -/** - * A variable controlling whether updates to the SDL screen surface should be - * synchronized with the vertical refresh, to avoid tearing. - * - * This variable can be set to the following values: - * - * - "0": Disable vsync - * - "1": Enable vsync - * - * By default SDL does not sync screen surface updates with vertical refresh. - */ -#define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" - -/** - * A variable controlling whether the Metal render driver select low power - * device over default one - * - * This variable can be set to the following values: - * - * - "0": Use the prefered OS device - * - "1": Select a low power one - * - * By default the prefered OS device is used. - */ -#define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" - -/** - * A variable containing a list of ROG gamepad capable mice. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" - -/** - * A variable containing a list of devices that are not ROG gamepad capable - * mice. - * - * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. - * - * The format of the string is a comma separated list of USB VID/PID pairs in - * hexadecimal form, e.g. - * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD - * - * The variable can also take the form of @file, in which case the named file - * will be loaded and interpreted as the value of the variable. - */ -#define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" - -/** - * A variable controlling if VSYNC is automatically disable if doesn't reach - * the enough FPS - * - * This variable can be set to the following values: - * - * - "0": It will be using VSYNC as defined in the main flag. Default - * - "1": If VSYNC was previously enabled, then it will disable VSYNC if - * doesn't reach enough speed - * - * By default SDL does not enable the automatic VSYNC - */ -#define SDL_HINT_PS2_DYNAMIC_VSYNC "SDL_PS2_DYNAMIC_VSYNC" - -/** - * A variable to control whether the return key on the soft keyboard should - * hide the soft keyboard on Android and iOS. - * - * The variable can be set to the following values: - * - * - "0": The return key will be handled as a key event. This is the behaviour - * of SDL <= 2.0.3. (default) - * - "1": The return key will hide the keyboard. - * - * The value of this hint is used at runtime, so it can be changed at any - * time. - */ -#define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" - -/** - * Tell SDL which Dispmanx layer to use on a Raspberry PI - * - * Also known as Z-order. The variable can take a negative or positive value. - * The default is 10000. - */ -#define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" - -/** - * Specify an "activity name" for screensaver inhibition. - * - * Some platforms, notably Linux desktops, list the applications which are - * inhibiting the screensaver or other power-saving features. - * - * This hint lets you specify the "activity name" sent to the OS when - * SDL_DisableScreenSaver() is used (or the screensaver is automatically - * disabled). The contents of this hint are used when the screensaver is - * disabled. You should use a string that describes what your program is doing - * (and, therefore, why the screensaver is disabled). For example, "Playing a - * game" or "Watching a video". - * - * Setting this to "" or leaving it unset will have SDL use a reasonable - * default: "Playing a game" or something similar. - * - * On targets where this is not supported, this hint does nothing. - */ -#define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" - -/** - * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as - * realtime. - * - * On some platforms, like Linux, a realtime priority thread may be subject to - * restrictions that require special handling by the application. This hint - * exists to let SDL know that the app is prepared to handle said - * restrictions. - * - * On Linux, SDL will apply the following configuration to any thread that - * becomes realtime: - * - * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy. - * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. - * - Exceeding this limit will result in the kernel sending SIGKILL to the - * app. - * - * Refer to the man pages for more information. - * - * This variable can be set to the following values: - * - * - "0": default platform specific behaviour - * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling - * policy - */ -#define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" - -/** - * A string specifying additional information to use with - * SDL_SetThreadPriority. - * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. - * - * pthread hint values are "current", "other", "fifo" and "rr". Currently no - * other platform hint values are defined but may be in the future. - */ -#define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" - -/** - * A string specifying SDL's threads stack size in bytes or "0" for the - * backend's default size - * - * Use this hint in case you need to set SDL's threads stack size to other - * than the default. This is specially useful if you build SDL against a non - * glibc libc library (such as musl) which provides a relatively small default - * thread stack size (a few kilobytes versus the default 8MB glibc uses). - * Support for this hint is currently available only in the pthread, Windows, - * and PSP backend. - * - * Instead of this hint, in 2.0.9 and later, you can use - * SDL_CreateThreadWithStackSize(). This hint only works with the classic - * SDL_CreateThread(). - */ -#define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE" - -/** - * A variable that controls the timer resolution, in milliseconds. - * - * The higher resolution the timer, the more frequently the CPU services timer - * interrupts, and the more precise delays are, but this takes up power and - * CPU time. This hint is only used on Windows. - * - * See this blog post for more information: - * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ - * - * If this variable is set to "0", the system timer resolution is not set. - * - * The default value is "1". This hint may be set at any time. - */ -#define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" - -/** - * A variable controlling whether touch events should generate synthetic mouse - * events - * - * This variable can be set to the following values: - * - * - "0": Touch events will not generate mouse events - * - "1": Touch events will generate mouse events - * - * By default SDL will generate mouse events for touch events - */ -#define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" - -/** - * A variable controlling which touchpad should generate synthetic mouse - * events - * - * This variable can be set to the following values: - * - * - "0": Only front touchpad should generate mouse events. Default - * - "1": Only back touchpad should generate mouse events. - * - "2": Both touchpads should generate mouse events. - * - * By default SDL will generate mouse events for all touch devices - */ -#define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_HINT_VITA_TOUCH_MOUSE_DEVICE" - -/** - * A variable controlling whether the Android / tvOS remotes should be listed - * as joystick devices, instead of sending keyboard events. - * - * This variable can be set to the following values: - * - * - "0": Remotes send enter/escape/arrow key events - * - "1": Remotes are available as 2 axis, 2 button joysticks (the default). - */ -#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" - -/** - * A variable controlling whether the screensaver is enabled. - * - * This variable can be set to the following values: - * - * - "0": Disable screensaver - * - "1": Enable screensaver - * - * By default SDL will disable the screensaver. - */ -#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" - -/** - * Tell the video driver that we only want a double buffer. - * - * By default, most lowlevel 2D APIs will use a triple buffer scheme that - * wastes no CPU time on waiting for vsync after issuing a flip, but - * introduces a frame of latency. On the other hand, using a double buffer - * scheme instead is recommended for cases where low latency is an important - * factor because we save a whole frame of latency. We do so by waiting for - * vsync immediately after issuing a flip, usually just after eglSwapBuffers - * call in the backend's *_SwapWindow function. - * - * Since it's driver-specific, it's only supported where possible and - * implemented. Currently supported the following drivers: - * - * - Wayland (wayland) - * - KMSDRM (kmsdrm) - * - Raspberry Pi (raspberrypi) - */ -#define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" - -/** - * A variable controlling whether the EGL window is allowed to be composited - * as transparent, rather than opaque. - * - * Most window systems will always render windows opaque, even if the surface - * format has an alpha channel. This is not always true, however, so by - * default SDL will try to enforce opaque composition. To override this - * behavior, you can set this hint to "1". - */ -#define SDL_HINT_VIDEO_EGL_ALLOW_TRANSPARENCY "SDL_VIDEO_EGL_ALLOW_TRANSPARENCY" - -/** - * A variable controlling whether the graphics context is externally managed. - * - * This variable can be set to the following values: - * - * - "0": SDL will manage graphics contexts that are attached to windows. - * - "1": Disable graphics context management on windows. - * - * By default SDL will manage OpenGL contexts in certain situations. For - * example, on Android the context will be automatically saved and restored - * when pausing the application. Additionally, some platforms will assume - * usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this - * behavior, which is desireable when the application manages the graphics - * context, such as an externally managed OpenGL context or attaching a Vulkan - * surface to the window. - */ -#define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT" - -/** - * If set to 1, then do not allow high-DPI windows. - * - * ("Retina" on Mac and iOS) - */ -#define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED" - -/** - * A variable that dictates policy for fullscreen Spaces on Mac OS X. - * - * This hint only applies to Mac OS X. - * - * The variable can be set to the following values: - * - * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and - * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their - * titlebars). - * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and - * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their - * titlebars). - * - * The default value is "1". This hint must be set before any windows are - * created. - */ -#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" - -/** - * Minimize your SDL_Window if it loses key focus when in fullscreen mode. - * - * Defaults to false. - */ -#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" - -/** - * A variable controlling whether the libdecor Wayland backend is allowed to - * be used. - * - * This variable can be set to the following values: - * - * - "0": libdecor use is disabled. - * - "1": libdecor use is enabled (default). - * - * libdecor is used over xdg-shell when xdg-decoration protocol is - * unavailable. - */ -#define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" - -/** - * A variable controlling whether the libdecor Wayland backend is preferred - * over native decorations. - * - * When this hint is set, libdecor will be used to provide window decorations, - * even if xdg-decoration is available. (Note that, by default, libdecor will - * use xdg-decoration itself if available). - * - * This variable can be set to the following values: - * - * - "0": libdecor is enabled only if server-side decorations are unavailable. - * - "1": libdecor is always enabled if available. - * - * libdecor is used over xdg-shell when xdg-decoration protocol is - * unavailable. - */ -#define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" - -/** - * A variable controlling whether video mode emulation is enabled under - * Wayland. - * - * When this hint is set, a standard set of emulated CVT video modes will be - * exposed for use by the application. If it is disabled, the only modes - * exposed will be the logical desktop size and, in the case of a scaled - * desktop, the native display resolution. - * - * This variable can be set to the following values: - * - * - "0": Video mode emulation is disabled. - * - "1": Video mode emulation is enabled. - * - * By default video mode emulation is enabled. - */ -#define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" - -/** - * Enable or disable mouse pointer warp emulation, needed by some older games. - * - * When this hint is set, any SDL will emulate mouse warps using relative - * mouse mode. This is required for some older games (such as Source engine - * games), which warp the mouse to the centre of the screen rather than using - * relative mouse motion. Note that relative mouse mode may have different - * mouse acceleration behaviour than pointer warps. - * - * This variable can be set to the following values: - * - * - "0": All mouse warps fail, as mouse warping is not available under - * wayland. - * - "1": Some mouse warps will be emulated by forcing relative mouse mode. - * - * If not set, this is automatically enabled unless an application uses - * relative mouse mode directly. - */ -#define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" - -/** - * A variable that is the address of another SDL_Window* (as a hex string - * formatted with "%p"). - * - * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is - * set to has SDL_WINDOW_OPENGL set (and running on WGL only, currently), then - * two things will occur on the newly created SDL_Window: - * - * 1. Its pixel format will be set to the same pixel format as this - * SDL_Window. This is needed for example when sharing an OpenGL context - * across multiple windows. - * - * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be - * used for OpenGL rendering. - * - * This variable can be set to the following values: The address (as a string - * "%p") of the SDL_Window* that new windows created with - * SDL_CreateWindowFrom() should share a pixel format with. - */ -#define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT" - -/** - * When calling SDL_CreateWindowFrom(), make the window compatible with - * OpenGL. - * - * This variable can be set to the following values: - * - * - "0": Don't add any graphics flags to the SDL_WindowFlags - * - "1": Add SDL_WINDOW_OPENGL to the SDL_WindowFlags - * - * By default SDL will not make the foreign window compatible with OpenGL. - */ -#define SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL "SDL_VIDEO_FOREIGN_WINDOW_OPENGL" - -/** - * When calling SDL_CreateWindowFrom(), make the window compatible with - * Vulkan. - * - * This variable can be set to the following values: - * - * - "0": Don't add any graphics flags to the SDL_WindowFlags - * - "1": Add SDL_WINDOW_VULKAN to the SDL_WindowFlags - * - * By default SDL will not make the foreign window compatible with Vulkan. - */ -#define SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN "SDL_VIDEO_FOREIGN_WINDOW_VULKAN" - -/** - * A variable specifying which shader compiler to preload when using the - * Chrome ANGLE binaries - * - * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can - * use two different sets of binaries, those compiled by the user from source - * or those provided by the Chrome browser. In the later case, these binaries - * require that SDL loads a DLL providing the shader compiler. - * - * This variable can be set to the following values: - * - * - "d3dcompiler_46.dll: default, best for Vista or later. - * - "d3dcompiler_43.dll: for XP support. - * - "none": do not load any library, useful if you compiled ANGLE from source - * and included the compiler in your binaries. - */ -#define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" - -/** - * A variable controlling whether X11 should use GLX or EGL by default - * - * This variable can be set to the following values: - * - * - "0": Use GLX - * - "1": Use EGL - * - * By default SDL will use GLX when both are present. - */ -#define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL" - -/** - * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint - * should be used. - * - * This variable can be set to the following values: - * - * - "0": Disable _NET_WM_BYPASS_COMPOSITOR - * - "1": Enable _NET_WM_BYPASS_COMPOSITOR - * - * By default SDL will use _NET_WM_BYPASS_COMPOSITOR - */ -#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" - -/** - * A variable controlling whether the X11 _NET_WM_PING protocol should be - * supported. - * - * This variable can be set to the following values: - * - * - "0": Disable _NET_WM_PING - * - "1": Enable _NET_WM_PING - * - * By default SDL will use _NET_WM_PING, but for applications that know they - * will not always be able to respond to ping requests in a timely manner they - * can turn it off to avoid the window manager thinking the app is hung. The - * hint is checked in CreateWindow. - */ -#define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" - -/** - * A variable forcing the visual ID chosen for new X11 windows - */ -#define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" - -/** - * A no-longer-used variable controlling whether the X11 Xinerama extension - * should be used. - * - * Before SDL 2.0.24, this would let apps and users disable Xinerama support - * on X11. Now SDL never uses Xinerama, and does not check for this hint at - * all. The preprocessor define is left here for source compatibility. - */ -#define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" - -/** - * A variable controlling whether the X11 XRandR extension should be used. - * - * This variable can be set to the following values: - * - * - "0": Disable XRandR - * - "1": Enable XRandR - * - * By default SDL will use XRandR. - */ -#define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" - -/** - * A no-longer-used variable controlling whether the X11 VidMode extension - * should be used. - * - * Before SDL 2.0.24, this would let apps and users disable XVidMode support - * on X11. Now SDL never uses XVidMode, and does not check for this hint at - * all. The preprocessor define is left here for source compatibility. - */ -#define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" - -/** - * Controls how the fact chunk affects the loading of a WAVE file. - * - * The fact chunk stores information about the number of samples of a WAVE - * file. The Standards Update from Microsoft notes that this value can be used - * to 'determine the length of the data in seconds'. This is especially useful - * for compressed formats (for which this is a mandatory chunk) if they - * produce multiple sample frames per block and truncating the block is not - * allowed. The fact chunk can exactly specify how many sample frames there - * should be in this case. - * - * Unfortunately, most application seem to ignore the fact chunk and so SDL - * ignores it by default as well. - * - * This variable can be set to the following values: - * - * - "truncate": Use the number of samples to truncate the wave data if the - * fact chunk is present and valid - * - "strict": Like "truncate", but raise an error if the fact chunk is - * invalid, not present for non-PCM formats, or if the data chunk doesn't - * have that many samples - * - "ignorezero": Like "truncate", but ignore fact chunk if the number of - * samples is zero - * - "ignore": Ignore fact chunk entirely (default) - */ -#define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" - -/** - * Controls how the size of the RIFF chunk affects the loading of a WAVE file. - * - * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE - * file) is not always reliable. In case the size is wrong, it's possible to - * just ignore it and step through the chunks until a fixed limit is reached. - * - * Note that files that have trailing data unrelated to the WAVE file or - * corrupt files may slow down the loading process without a reliable - * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. - * Use the environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. - * - * This variable can be set to the following values: - * - * - "force": Always use the RIFF chunk size as a boundary for the chunk - * search - * - "ignorezero": Like "force", but a zero size searches up to 4 GiB - * (default) - * - "ignore": Ignore the RIFF chunk size and always search up to 4 GiB - * - "maximum": Search for chunks until the end of file (not recommended) - */ -#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" - -/** - * Controls how a truncated WAVE file is handled. - * - * A WAVE file is considered truncated if any of the chunks are incomplete or - * the data chunk size is not a multiple of the block size. By default, SDL - * decodes until the first incomplete block, as most applications seem to do. - * - * This variable can be set to the following values: - * - * - "verystrict": Raise an error if the file is truncated - * - "strict": Like "verystrict", but the size of the RIFF chunk is ignored - * - "dropframe": Decode until the first incomplete sample frame - * - "dropblock": Decode until the first incomplete block (default) - */ -#define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" - -/** - * Tell SDL not to name threads on Windows with the 0x406D1388 Exception. - * - * The 0x406D1388 Exception is a trick used to inform Visual Studio of a - * thread's name, but it tends to cause problems with other debuggers, and the - * .NET runtime. Note that SDL 2.0.6 and later will still use the (safer) - * SetThreadDescription API, introduced in the Windows 10 Creators Update, if - * available. - * - * The variable can be set to the following values: - * - * - "0": SDL will raise the 0x406D1388 Exception to name threads. This is the - * default behavior of SDL <= 2.0.4. - * - "1": SDL will not raise this exception, and threads will be unnamed. - * (default) This is necessary with .NET languages or debuggers that aren't - * Visual Studio. - */ -#define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING" - -/** - * Controls whether menus can be opened with their keyboard shortcut - * (Alt+mnemonic). - * - * If the mnemonics are enabled, then menus can be opened by pressing the Alt - * key and the corresponding mnemonic (for example, Alt+F opens the File - * menu). However, in case an invalid mnemonic is pressed, Windows makes an - * audible beep to convey that nothing happened. This is true even if the - * window has no menu at all! - * - * Because most SDL applications don't have menus, and some want to use the - * Alt key for other purposes, SDL disables mnemonics (and the beeping) by - * default. - * - * Note: This also affects keyboard events: with mnemonics enabled, when a - * menu is opened from the keyboard, you will not receive a KEYUP event for - * the mnemonic key, and *might* not receive one for Alt. - * - * This variable can be set to the following values: - * - * - "0": Alt+mnemonic does nothing, no beeping. (default) - * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. - */ -#define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" - -/** - * A variable controlling whether the windows message loop is processed by SDL - * - * This variable can be set to the following values: - * - * - "0": The window message loop is not run - * - "1": The window message loop is processed in SDL_PumpEvents() - * - * By default SDL will process the windows message loop - */ -#define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" - -/** - * Force SDL to use Critical Sections for mutexes on Windows. - * - * On Windows 7 and newer, Slim Reader/Writer Locks are available. They offer - * better performance, allocate no kernel resources and use less memory. SDL - * will fall back to Critical Sections on older OS versions or if forced to by - * this hint. - * - * This variable can be set to the following values: - * - * - "0": Use SRW Locks when available. If not, fall back to Critical - * Sections. (default) - * - "1": Force the use of Critical Sections in all cases. - */ -#define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS" - -/** - * Force SDL to use Kernel Semaphores on Windows. - * - * Kernel Semaphores are inter-process and require a context switch on every - * interaction. On Windows 8 and newer, the WaitOnAddress API is available. - * Using that and atomics to implement semaphores increases performance. SDL - * will fall back to Kernel Objects on older OS versions or if forced to by - * this hint. - * - * This variable can be set to the following values: - * - * - "0": Use Atomics and WaitOnAddress API when available. If not, fall back - * to Kernel Objects. (default) - * - "1": Force the use of Kernel Objects in all cases. - */ -#define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" - -/** - * A variable to specify custom icon resource id from RC file on Windows - * platform - */ -#define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" - -/** - * A variable to specify custom icon resource id from RC file on Windows - * platform - */ -#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" - -/** - * Tell SDL not to generate window-close events for Alt+F4 on Windows. - * - * The variable can be set to the following values: - * - * - "0": SDL will generate a window-close event when it sees Alt+F4. - * - "1": SDL will only do normal key handling for Alt+F4. - */ -#define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4" - -/** - * Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. - * - * Direct3D 9Ex contains changes to state management that can eliminate device - * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may - * require some changes to your application to cope with the new behavior, so - * this is disabled by default. - * - * This hint must be set before initializing the video subsystem. - * - * For more information on Direct3D 9Ex, see: - - * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex - * - - * https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements - * - * This variable can be set to the following values: - * - * - "0": Use the original Direct3D 9 API (default) - * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex - * is unavailable) - */ -#define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" - -/** - * Controls whether SDL will declare the process to be DPI aware. - * - * This hint must be set before initializing the video subsystem. - * - * The main purpose of declaring DPI awareness is to disable OS bitmap scaling - * of SDL windows on monitors with a DPI scale factor. - * - * This hint is equivalent to requesting DPI awareness via external means - * (e.g. calling SetProcessDpiAwarenessContext) and does not cause SDL to use - * a virtualized coordinate system, so it will generally give you 1 SDL - * coordinate = 1 pixel even on high-DPI displays. - * - * For more information, see: - * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows - * - * This variable can be set to the following values: - * - * - "": Do not change the DPI awareness (default). - * - "unaware": Declare the process as DPI unaware. (Windows 8.1 and later). - * - "system": Request system DPI awareness. (Vista and later). - * - "permonitor": Request per-monitor DPI awareness. (Windows 8.1 and later). - * - "permonitorv2": Request per-monitor V2 DPI awareness. (Windows 10, - * version 1607 and later). The most visible difference from "permonitor" is - * that window title bar will be scaled to the visually correct size when - * dragging between monitors with different scale factors. This is the - * preferred DPI awareness level. - * - * If the requested DPI awareness is not available on the currently running - * OS, SDL will try to request the best available match. - */ -#define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS" - -/** - * Uses DPI-scaled points as the SDL coordinate system on Windows. - * - * This changes the SDL coordinate system units to be DPI-scaled points, - * rather than pixels everywhere. This means windows will be appropriately - * sized, even when created on high-DPI displays with scaling. - * - * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling - * in Windows display settings, will create a window with an 800x600 client - * area (in pixels). - * - * Setting this to "1" implicitly requests process DPI awareness (setting - * SDL_WINDOWS_DPI_AWARENESS is unnecessary), and forces - * SDL_WINDOW_ALLOW_HIGHDPI on all windows. - * - * This variable can be set to the following values: - * - * - "0": SDL coordinates equal Windows coordinates. No automatic window - * resizing when dragging between monitors with different scale factors - * (unless this is performed by Windows itself, which is the case when the - * process is DPI unaware). - * - "1": SDL coordinates are in DPI-scaled points. Automatically resize - * windows as needed on displays with non-100% scale factors. - */ -#define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING" - -/** - * A variable controlling whether the window frame and title bar are - * interactive when the cursor is hidden - * - * This variable can be set to the following values: - * - * - "0": The window frame is not interactive when the cursor is hidden (no - * move, resize, etc) - * - "1": The window frame is interactive when the cursor is hidden - * - * By default SDL will allow interaction with the window frame when the cursor - * is hidden - */ -#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" - -/** - * A variable controlling whether the window is activated when the - * SDL_ShowWindow function is called - * - * This variable can be set to the following values: - * - * - "0": The window is activated when the SDL_ShowWindow function is called - * - "1": The window is not activated when the SDL_ShowWindow function is - * called - * - * By default SDL will activate the window when the SDL_ShowWindow function is - * called - */ -#define SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN "SDL_WINDOW_NO_ACTIVATION_WHEN_SHOWN" - -/** Allows back-button-press events on Windows Phone to be marked as handled - * - * Windows Phone devices typically feature a Back button. When pressed, - * the OS will emit back-button-press events, which apps are expected to - * handle in an appropriate manner. If apps do not explicitly mark these - * events as 'Handled', then the OS will invoke its default behavior for - * unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to - * terminate the app (and attempt to switch to the previous app, or to the - * device's home screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL - * to mark back-button-press events as Handled, if and when one is sent to - * the app. - * - * Internally, Windows Phone sends back button events as parameters to - * special back-button-press callback functions. Apps that need to respond - * to back-button-press events are expected to register one or more - * callback functions for such, shortly after being launched (during the - * app's initialization phase). After the back button is pressed, the OS - * will invoke these callbacks. If the app's callback(s) do not explicitly - * mark the event as handled by the time they return, or if the app never - * registers one of these callback, the OS will consider the event - * un-handled, and it will apply its default back button behavior (terminate - * the app). - * - * SDL registers its own back-button-press callback with the Windows Phone - * OS. This callback will emit a pair of SDL key-press events (SDL_KEYDOWN - * and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which - * it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON. - * If the hint's value is set to "1", the back button event's Handled - * property will get set to 'true'. If the hint's value is set to something - * else, or if it is unset, SDL will leave the event's Handled property - * alone. (By default, the OS sets this property to 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_KEYUP events can be listened-for. Listening for - * either event type is suitable.) Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON - * set by such a callback, will be applied to the OS' current - * back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found - * at the following page, on Microsoft's developer site: - * - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** Label text for a WinRT app's privacy policy link - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT, - * Microsoft mandates that this policy be available via the Windows Settings charm. - * SDL provides code to add a link there, with its label text being set via the - * optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A separate - * hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the - * policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". This hint should only be set during app - * initialization, preferably before any calls to SDL_Init(). - * - * For additional information on linking to a privacy policy, see the documentation for - * SDL_HINT_WINRT_PRIVACY_POLICY_URL. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A URL to a WinRT app's privacy policy - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - -/** - * Mark X11 windows as override-redirect. - * - * If set, this _might_ increase framerate at the expense of the desktop not - * working as expected. Override-redirect windows aren't noticed by the window - * manager at all. - * - * You should probably only use this for fullscreen windows, and you probably - * shouldn't even use it for that. But it's here if you want to try! - */ -#define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" - -/** - * A variable that lets you disable the detection and use of Xinput gamepad - * devices - * - * The variable can be set to the following values: - * - * - "0": Disable XInput detection (only uses direct input) - * - "1": Enable XInput detection (the default) - */ -#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" - -/** - * A variable that lets you disable the detection and use of DirectInput - * gamepad devices - * - * The variable can be set to the following values: - * - * - "0": Disable DirectInput detection (only uses XInput) - * - "1": Enable DirectInput detection (the default) - */ -#define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED" - -/** - * A variable that causes SDL to use the old axis and button mapping for - * XInput devices. - * - * This hint is for backwards compatibility only and will be removed in SDL - * 2.1 - * - * The default value is "0". This hint must be set before SDL_Init() - */ -#define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING" - -/** - * A variable that causes SDL to not ignore audio "monitors" - * - * This is currently only used for PulseAudio and ignored elsewhere. - * - * By default, SDL ignores audio devices that aren't associated with physical - * hardware. Changing this hint to "1" will expose anything SDL sees that - * appears to be an audio source or sink. This will add "devices" to the list - * that the user probably doesn't want or need, but it can be useful in - * scenarios where you want to hook up SDL to some sort of virtual device, - * etc. - * - * The default value is "0". This hint must be set before SDL_Init(). - * - * This hint is available since SDL 2.0.16. Before then, virtual devices are - * always ignored. - */ -#define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" - -/** - * A variable that forces X11 windows to create as a custom type. - * - * This is currently only used for X11 and ignored elsewhere. - * - * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to - * report to the window manager the type of window it wants to create. This - * might be set to various things if SDL_WINDOW_TOOLTIP or - * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that - * haven't set a specific type, this hint can be used to specify a custom - * type. For example, a dock window might set this to - * "_NET_WM_WINDOW_TYPE_DOCK". - * - * If not set or set to "", this hint is ignored. This hint must be set before - * the SDL_CreateWindow() call that it is intended to affect. - * - * This hint is available since SDL 2.0.22. - */ -#define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" - -/** - * A variable that decides whether to send SDL_QUIT when closing the final - * window. - * - * By default, SDL sends an SDL_QUIT event when there is only one window and - * it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most apps - * would also take the loss of this window as a signal to terminate the - * program. - * - * However, it's not unreasonable in some cases to have the program continue - * to live on, perhaps to create new windows later. - * - * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event when - * the final window is requesting to close. Note that in this case, there are - * still other legitimate reasons one might get an SDL_QUIT event: choosing - * "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. - * - * The default value is "1". This hint can be changed at any time. - * - * This hint is available since SDL 2.0.22. Before then, you always get an - * SDL_QUIT event when closing the final window. - */ -#define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" - - -/** - * A variable that decides what video backend to use. - * - * By default, SDL will try all available video backends in a reasonable order - * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "x11" if, say, you are on Wayland but want - * to try talking to the X server instead. - * - * This functionality has existed since SDL 2.0.0 (indeed, before that) but - * before 2.0.22 this was an environment variable only. In 2.0.22, it was - * upgraded to a full SDL hint, so you can set the environment variable as - * usual or programatically set the hint with SDL_SetHint, which won't - * propagate to child processes. - * - * The default value is unset, in which case SDL will try to figure out the - * best video backend on your behalf. This hint needs to be set before - * SDL_Init() is called to be useful. - * - * This hint is available since SDL 2.0.22. Before then, you could set the - * environment variable to get the same effect. - */ -#define SDL_HINT_VIDEODRIVER "SDL_VIDEODRIVER" - -/** - * A variable that decides what audio backend to use. - * - * By default, SDL will try all available audio backends in a reasonable order - * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "alsa" if, say, you are on PulseAudio but - * want to try talking to the lower level instead. - * - * This functionality has existed since SDL 2.0.0 (indeed, before that) but - * before 2.0.22 this was an environment variable only. In 2.0.22, it was - * upgraded to a full SDL hint, so you can set the environment variable as - * usual or programatically set the hint with SDL_SetHint, which won't - * propagate to child processes. - * - * The default value is unset, in which case SDL will try to figure out the - * best audio backend on your behalf. This hint needs to be set before - * SDL_Init() is called to be useful. - * - * This hint is available since SDL 2.0.22. Before then, you could set the - * environment variable to get the same effect. - */ -#define SDL_HINT_AUDIODRIVER "SDL_AUDIODRIVER" - -/** - * A variable that decides what KMSDRM device to use. - * - * Internally, SDL might open something like "/dev/dri/cardNN" to access - * KMSDRM functionality, where "NN" is a device index number. - * - * SDL makes a guess at the best index to use (usually zero), but the app or - * user can set this hint to a number between 0 and 99 to force selection. - * - * This hint is available since SDL 2.24.0. - */ -#define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" - - -/** - * A variable that treats trackpads as touch devices. - * - * On macOS (and possibly other platforms in the future), SDL will report - * touches on a trackpad as mouse input, which is generally what users expect - * from this device; however, these are often actually full multitouch-capable - * touch devices, so it might be preferable to some apps to treat them as - * such. - * - * Setting this hint to true will make the trackpad input report as a - * multitouch device instead of a mouse. The default is false. - * - * Note that most platforms don't support this hint. As of 2.24.0, it only - * supports MacBooks' trackpads on macOS. Others may follow later. - * - * This hint is checked during SDL_Init and can not be changed after. - * - * This hint is available since SDL 2.24.0. - */ -#define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" - -/** - * Cause SDL to call dbus_shutdown() on quit. - * - * This is useful as a debug tool to validate memory leaks, but shouldn't ever - * be set in production applications, as other libraries used by the - * application might use dbus under the hood and this cause cause crashes if - * they continue after SDL_Quit(). - * - * This variable can be set to the following values: - * - * - "0": SDL will not call dbus_shutdown() on quit (default) - * - "1": SDL will call dbus_shutdown() on quit - * - * This hint is available since SDL 2.30.0. - */ -#define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" - -/** - * Specify if SDL_RWFromFile should use the resource dir on Apple platforms. - * - * SDL2 has always done this on Apple platforms, but it can be surprising to - * try opening a path to discover that SDL adjusts the path to elsewhere, so - * this hint allows that behavior to be disabled. - * - * If running from a App Bundle, this will be MyApp.app/Contents/Resources. If - * running as a normal Unix-like process, this will be the directory where the - * running binary lives. Setting this hint to 0 avoids this and just uses the - * requested path as-is. - * - * This variable can be set to the following values: - * - * - "0": SDL will not use the app resource directory. - * - "1": SDL will use the app's resource directory (default). - * - * This hint is available since SDL 2.32.0. - */ -#define SDL_HINT_APPLE_RWFROMFILE_USE_RESOURCES "SDL_APPLE_RWFROMFILE_USE_RESOURCES" - - -/** - * An enumeration of hint priorities - */ -typedef enum SDL_HintPriority -{ - SDL_HINT_DEFAULT, - SDL_HINT_NORMAL, - SDL_HINT_OVERRIDE -} SDL_HintPriority; - - -/** - * Set a hint with a specific priority. - * - * The priority controls the behavior when setting a hint that already has a - * value. Hints will replace existing hints of their priority and lower. - * Environment variables are considered to have override priority. - * - * \param name the hint to set. - * \param value the value of the hint variable. - * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetHint - * \sa SDL_SetHint - */ -extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, - const char *value, - SDL_HintPriority priority); - -/** - * Set a hint with normal priority. - * - * Hints will not be set if there is an existing override hint or environment - * variable that takes precedence. You can use SDL_SetHintWithPriority() to - * set the hint with override priority instead. - * - * \param name the hint to set. - * \param value the value of the hint variable. - * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetHint - * \sa SDL_SetHintWithPriority - */ -extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, - const char *value); - -/** - * Reset a hint to the default value. - * - * This will reset a hint to the value of the environment variable, or NULL if - * the environment isn't set. Callbacks will be called normally with this - * change. - * - * \param name the hint to set. - * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GetHint - * \sa SDL_SetHint - */ -extern DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); - -/** - * Reset all hints to the default values. - * - * This will reset all hints to the value of the associated environment - * variable, or NULL if the environment isn't set. Callbacks will be called - * normally with this change. - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_GetHint - * \sa SDL_SetHint - * \sa SDL_ResetHint - */ -extern DECLSPEC void SDLCALL SDL_ResetHints(void); - -/** - * Get the value of a hint. - * - * \param name the hint to query. - * \returns the string value of a hint or NULL if the hint isn't set. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetHint - * \sa SDL_SetHintWithPriority - */ -extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); - -/** - * Get the boolean value of a hint variable. - * - * \param name the name of the hint to get the boolean value from. - * \param default_value the value to return if the hint does not exist. - * \returns the boolean value of a hint or the provided default value if the - * hint does not exist. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_GetHint - * \sa SDL_SetHint - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); - -/** - * Type definition of the hint callback function. - * - * \param userdata what was passed as `userdata` to SDL_AddHintCallback(). - * \param name what was passed as `name` to SDL_AddHintCallback(). - * \param oldValue the previous hint value. - * \param newValue the new value hint is to be set to. - */ -typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); - -/** - * Add a function to watch a particular hint. - * - * \param name the hint to watch. - * \param callback An SDL_HintCallback function that will be called when the - * hint value changes. - * \param userdata a pointer to pass to the callback function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DelHintCallback - */ -extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, - SDL_HintCallback callback, - void *userdata); - -/** - * Remove a function watching a particular hint. - * - * \param name the hint being watched. - * \param callback An SDL_HintCallback function that will be called when the - * hint value changes. - * \param userdata a pointer being passed to the callback function. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AddHintCallback - */ -extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, - SDL_HintCallback callback, - void *userdata); - -/** - * Clear all hints. - * - * This function is automatically called during SDL_Quit(), and deletes all - * callbacks without calling them and frees all memory associated with hints. - * If you're calling this from application code you probably want to call - * SDL_ResetHints() instead. - * - * This function will be removed from the API the next time we rev the ABI. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ResetHints - */ -extern DECLSPEC void SDLCALL SDL_ClearHints(void); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_hints_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_joystick.h b/code/thirdparty/SDL2-2.32.8/include/SDL_joystick.h deleted file mode 100644 index 668db5e30f..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_joystick.h +++ /dev/null @@ -1,1088 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryJoystick - * - * Include file for SDL joystick event handling - * - * The term "device_index" identifies currently plugged in joystick devices - * between 0 and SDL_NumJoysticks(), with the exact joystick behind a - * device_index changing as joysticks are plugged and unplugged. - * - * The term "instance_id" is the current instantiation of a joystick device in - * the system, if the joystick is removed and then re-inserted then it will - * get a new instance_id, instance_id's are monotonically increasing - * identifiers of a joystick plugged in. - * - * The term "player_index" is the number assigned to a player on a specific - * controller. For XInput controllers this returns the XInput user index. Many - * joysticks will not be able to supply this information. - * - * The term JoystickGUID is a stable 128-bit identifier for a joystick device - * that does not change over time, it identifies class of the device (a X360 - * wired controller for example). This identifier is platform dependent. - */ - -#ifndef SDL_joystick_h_ -#define SDL_joystick_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_guid.h" -#include "SDL_mutex.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \file SDL_joystick.h - * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system - * for joysticks, and load appropriate drivers. - * - * If you would like to receive joystick updates while the application - * is in the background, you should set the following hint before calling - * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS - */ - -/** - * The joystick structure used to identify an SDL joystick - */ -#ifdef SDL_THREAD_SAFETY_ANALYSIS -extern SDL_mutex *SDL_joystick_lock; -#endif -struct _SDL_Joystick; -typedef struct _SDL_Joystick SDL_Joystick; - -/** - * A structure that encodes the stable unique id for a joystick device. - * - * This is just a standard SDL_GUID by a different name. - */ -typedef SDL_GUID SDL_JoystickGUID; - -/** - * This is a unique ID for a joystick for the time it is connected to the - * system, and is never reused for the lifetime of the application. - * - * If the joystick is disconnected and reconnected, it will get a new ID. - * - * The ID value starts at 0 and increments from there. The value -1 is an - * invalid ID. - */ -typedef Sint32 SDL_JoystickID; - -typedef enum -{ - SDL_JOYSTICK_TYPE_UNKNOWN, - SDL_JOYSTICK_TYPE_GAMECONTROLLER, - SDL_JOYSTICK_TYPE_WHEEL, - SDL_JOYSTICK_TYPE_ARCADE_STICK, - SDL_JOYSTICK_TYPE_FLIGHT_STICK, - SDL_JOYSTICK_TYPE_DANCE_PAD, - SDL_JOYSTICK_TYPE_GUITAR, - SDL_JOYSTICK_TYPE_DRUM_KIT, - SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE -} SDL_JoystickType; - -typedef enum -{ - SDL_JOYSTICK_POWER_UNKNOWN = -1, - SDL_JOYSTICK_POWER_EMPTY, /* <= 5% */ - SDL_JOYSTICK_POWER_LOW, /* <= 20% */ - SDL_JOYSTICK_POWER_MEDIUM, /* <= 70% */ - SDL_JOYSTICK_POWER_FULL, /* <= 100% */ - SDL_JOYSTICK_POWER_WIRED, - SDL_JOYSTICK_POWER_MAX -} SDL_JoystickPowerLevel; - -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - -/* Function prototypes */ - -/** - * Locking for multi-threaded access to the joystick API - * - * If you are using the joystick API or handling events from multiple threads - * you should use these locking functions to protect access to the joysticks. - * - * In particular, you are guaranteed that the joystick list won't change, so - * the API functions that take a joystick index will be valid, and joystick - * and game controller events will not be delivered. - * - * As of SDL 2.26.0, you can take the joystick lock around reinitializing the - * joystick subsystem, to prevent other threads from seeing joysticks in an - * uninitialized state. However, all open joysticks will be closed and SDL - * functions called with them will fail. - * - * \since This function is available since SDL 2.0.7. - */ -extern DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); - - -/** - * Unlocking for multi-threaded access to the joystick API - * - * If you are using the joystick API or handling events from multiple threads - * you should use these locking functions to protect access to the joysticks. - * - * In particular, you are guaranteed that the joystick list won't change, so - * the API functions that take a joystick index will be valid, and joystick - * and game controller events will not be delivered. - * - * \since This function is available since SDL 2.0.7. - */ -extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); - -/** - * Count the number of joysticks attached to the system. - * - * \returns the number of attached joysticks on success or a negative error - * code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickName - * \sa SDL_JoystickPath - * \sa SDL_JoystickOpen - */ -extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); - -/** - * Get the implementation dependent name of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system). - * \returns the name of the selected joystick. If no name can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickName - * \sa SDL_JoystickOpen - */ -extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); - -/** - * Get the implementation dependent path of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system). - * \returns the path of the selected joystick. If no path can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_JoystickPath - * \sa SDL_JoystickOpen - */ -extern DECLSPEC const char *SDLCALL SDL_JoystickPathForIndex(int device_index); - -/** - * Get the player index of a joystick, or -1 if it's not available This can be - * called before any joysticks are opened. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index); - -/** - * Get the implementation-dependent GUID for the joystick at a given device - * index. - * - * This function can be called before any joysticks are opened. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the GUID of the selected joystick. If called on an invalid index, - * this function returns a zero GUID. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetGUID - * \sa SDL_JoystickGetGUIDString - */ -extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index); - -/** - * Get the USB vendor ID of a joystick, if available. - * - * This can be called before any joysticks are opened. If the vendor ID isn't - * available this function returns 0. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the USB vendor ID of the selected joystick. If called on an - * invalid index, this function returns zero. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index); - -/** - * Get the USB product ID of a joystick, if available. - * - * This can be called before any joysticks are opened. If the product ID isn't - * available this function returns 0. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the USB product ID of the selected joystick. If called on an - * invalid index, this function returns zero. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index); - -/** - * Get the product version of a joystick, if available. - * - * This can be called before any joysticks are opened. If the product version - * isn't available this function returns 0. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the product version of the selected joystick. If called on an - * invalid index, this function returns zero. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index); - -/** - * Get the type of a joystick, if available. - * - * This can be called before any joysticks are opened. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the SDL_JoystickType of the selected joystick. If called on an - * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index); - -/** - * Get the instance ID of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param device_index the index of the joystick to query (the N'th joystick - * on the system. - * \returns the instance id of the selected joystick. If called on an invalid - * index, this function returns -1. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index); - -/** - * Open a joystick for use. - * - * The `device_index` argument refers to the N'th joystick presently - * recognized by SDL on the system. It is **NOT** the same as the instance ID - * used to identify the joystick in future events. See - * SDL_JoystickInstanceID() for more details about instance IDs. - * - * The joystick subsystem must be initialized before a joystick can be opened - * for use. - * - * \param device_index the index of the joystick to query. - * \returns a joystick identifier or NULL if an error occurred; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickClose - * \sa SDL_JoystickInstanceID - */ -extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); - -/** - * Get the SDL_Joystick associated with an instance id. - * - * \param instance_id the instance id to get the SDL_Joystick for. - * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.4. - */ -extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id); - -/** - * Get the SDL_Joystick associated with a player index. - * - * \param player_index the player index to get the SDL_Joystick for. - * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index); - -/** - * Attach a new virtual joystick. - * - * \returns the joystick's device index, or -1 if an error occurred. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type, - int naxes, - int nbuttons, - int nhats); - -/** - * The structure that defines an extended virtual joystick description - * - * The caller must zero the structure and then initialize the version with - * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to - * SDL_JoystickAttachVirtualEx() All other elements of this structure are - * optional and can be left 0. - * - * \sa SDL_JoystickAttachVirtualEx - */ -typedef struct SDL_VirtualJoystickDesc -{ - Uint16 version; /**< `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` */ - Uint16 type; /**< `SDL_JoystickType` */ - Uint16 naxes; /**< the number of axes on this joystick */ - Uint16 nbuttons; /**< the number of buttons on this joystick */ - Uint16 nhats; /**< the number of hats on this joystick */ - Uint16 vendor_id; /**< the USB vendor ID of this joystick */ - Uint16 product_id; /**< the USB product ID of this joystick */ - Uint16 padding; /**< unused */ - Uint32 button_mask; /**< A mask of which buttons are valid for this controller - e.g. (1 << SDL_CONTROLLER_BUTTON_A) */ - Uint32 axis_mask; /**< A mask of which axes are valid for this controller - e.g. (1 << SDL_CONTROLLER_AXIS_LEFTX) */ - const char *name; /**< the name of the joystick */ - - void *userdata; /**< User data pointer passed to callbacks */ - void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ - void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - int (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_JoystickRumble() */ - int (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_JoystickRumbleTriggers() */ - int (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_JoystickSetLED() */ - int (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_JoystickSendEffect() */ - -} SDL_VirtualJoystickDesc; - -/** - * The current version of the SDL_VirtualJoystickDesc structure - */ -#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 - -/** - * Attach a new virtual joystick with extended properties. - * - * \returns the joystick's device index, or -1 if an error occurred. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtualEx(const SDL_VirtualJoystickDesc *desc); - -/** - * Detach a virtual joystick. - * - * \param device_index a value previously returned from - * SDL_JoystickAttachVirtual(). - * \returns 0 on success, or -1 if an error occurred. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index); - -/** - * Query whether or not the joystick at a given device index is virtual. - * - * \param device_index a joystick device index. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index); - -/** - * Set values on an opened, virtual-joystick's axis. - * - * Please note that values set here will not be applied until the next call to - * SDL_JoystickUpdate, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * Note that when sending trigger axes, you should scale the value to the full - * range of Sint16. For example, a trigger at rest would have the value of - * `SDL_JOYSTICK_AXIS_MIN`. - * - * \param joystick the virtual joystick on which to set state. - * \param axis the specific axis on the virtual joystick to set. - * \param value the new value for the specified axis. - * \returns 0 on success, -1 on error. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); - -/** - * Set values on an opened, virtual-joystick's button. - * - * Please note that values set here will not be applied until the next call to - * SDL_JoystickUpdate, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param button the specific button on the virtual joystick to set. - * \param value the new value for the specified button. - * \returns 0 on success, -1 on error. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); - -/** - * Set values on an opened, virtual-joystick's hat. - * - * Please note that values set here will not be applied until the next call to - * SDL_JoystickUpdate, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param hat the specific hat on the virtual joystick to set. - * \param value the new value for the specified hat. - * \returns 0 on success, -1 on error. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); - -/** - * Get the implementation dependent name of a joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the name of the selected joystick. If no name can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickNameForIndex - * \sa SDL_JoystickOpen - */ -extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick); - -/** - * Get the implementation dependent path of a joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the path of the selected joystick. If no path can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_JoystickPathForIndex - */ -extern DECLSPEC const char *SDLCALL SDL_JoystickPath(SDL_Joystick *joystick); - -/** - * Get the player index of an opened joystick. - * - * For XInput controllers this returns the XInput user index. Many joysticks - * will not be able to supply this information. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the player index, or -1 if it's not available. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick); - -/** - * Set the player index of an opened joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \param player_index Player index to assign to this joystick, or -1 to clear - * the player index and turn off player LEDs. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index); - -/** - * Get the implementation-dependent GUID for the joystick. - * - * This function requires an open joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the GUID of the given joystick. If called on an invalid index, - * this function returns a zero GUID; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetDeviceGUID - * \sa SDL_JoystickGetGUIDString - */ -extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick); - -/** - * Get the USB vendor ID of an opened joystick, if available. - * - * If the vendor ID isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick); - -/** - * Get the USB product ID of an opened joystick, if available. - * - * If the product ID isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the USB product ID of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); - -/** - * Get the product version of an opened joystick, if available. - * - * If the product version isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the product version of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick); - -/** - * Get the firmware version of an opened joystick, if available. - * - * If the firmware version isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the firmware version of the selected joystick, or 0 if - * unavailable. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetFirmwareVersion(SDL_Joystick *joystick); - -/** - * Get the serial number of an opened joystick, if available. - * - * Returns the serial number of the joystick, or NULL if it is not available. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the serial number of the selected joystick, or NULL if - * unavailable. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick); - -/** - * Get the type of an opened joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). - * \returns the SDL_JoystickType of the selected joystick. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick); - -/** - * Get an ASCII string representation for a given SDL_JoystickGUID. - * - * You should supply at least 33 bytes for pszGUID. - * - * \param guid the SDL_JoystickGUID you wish to convert to string. - * \param pszGUID buffer in which to write the ASCII string. - * \param cbGUID the size of pszGUID. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetDeviceGUID - * \sa SDL_JoystickGetGUID - * \sa SDL_JoystickGetGUIDFromString - */ -extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID); - -/** - * Convert a GUID string into a SDL_JoystickGUID structure. - * - * Performs no error checking. If this function is given a string containing - * an invalid GUID, the function will silently succeed, but the GUID generated - * will not be useful. - * - * \param pchGUID string containing an ASCII representation of a GUID. - * \returns a SDL_JoystickGUID structure. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetGUIDString - */ -extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID); - -/** - * Get the device information encoded in a SDL_JoystickGUID structure - * - * \param guid the SDL_JoystickGUID you wish to get info about. - * \param vendor A pointer filled in with the device VID, or 0 if not - * available. - * \param product A pointer filled in with the device PID, or 0 if not - * available. - * \param version A pointer filled in with the device version, or 0 if not - * available. - * \param crc16 A pointer filled in with a CRC used to distinguish different - * products with the same VID/PID, or 0 if not available. - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_JoystickGetDeviceGUID - */ -extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16); - -/** - * Get the status of a specified joystick. - * - * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickClose - * \sa SDL_JoystickOpen - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick); - -/** - * Get the instance ID of an opened joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the instance ID of the specified joystick on success or a negative - * error code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickOpen - */ -extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick); - -/** - * Get the number of general axis controls on a joystick. - * - * Often, the directional pad on a game controller will either look like 4 - * separate buttons or a POV hat, and not axes, but all of this is up to the - * device and platform. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of axis controls/number of axes on success or a - * negative error code on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetAxis - * \sa SDL_JoystickOpen - */ -extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); - -/** - * Get the number of trackballs on a joystick. - * - * Joystick trackballs have only relative motion events associated with them - * and their state cannot be polled. - * - * Most joysticks do not have trackballs. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of trackballs on success or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetBall - */ -extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); - -/** - * Get the number of POV hats on a joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of POV hats on success or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetHat - * \sa SDL_JoystickOpen - */ -extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); - -/** - * Get the number of buttons on a joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of buttons on success or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickGetButton - * \sa SDL_JoystickOpen - */ -extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick); - -/** - * Update the current state of the open joysticks. - * - * This is called automatically by the event loop if any joystick events are - * enabled. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickEventState - */ -extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); - -/** - * Enable/disable joystick event polling. - * - * If joystick events are disabled, you must call SDL_JoystickUpdate() - * yourself and manually check the state of the joystick when you want - * joystick information. - * - * It is recommended that you leave joystick event handling enabled. - * - * **WARNING**: Calling this function may delete all events currently in SDL's - * event queue. - * - * While `param` is meant to be one of `SDL_QUERY`, `SDL_IGNORE`, or - * `SDL_ENABLE`, this function accepts any value, with any non-zero value that - * isn't `SDL_QUERY` being treated as `SDL_ENABLE`. - * - * If SDL was built with events disabled (extremely uncommon!), this will do - * nothing and always return `SDL_IGNORE`. - * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. - * \returns If `state` is `SDL_QUERY` then the current state is returned, - * otherwise `state` is returned (even if it was not one of the - * allowed values). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GameControllerEventState - */ -extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); - -/* Limits for joystick axes... */ -#define SDL_JOYSTICK_AXIS_MAX 32767 -#define SDL_JOYSTICK_AXIS_MIN -32768 - -/** - * Get the current state of an axis control on a joystick. - * - * SDL makes no promises about what part of the joystick any given axis refers - * to. Your game should have some sort of configuration UI to let users - * specify what each axis should be bound to. Alternately, SDL's higher-level - * Game Controller API makes a great effort to apply order to this lower-level - * interface, so you know that a specific axis is the "left thumb stick," etc. - * - * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to - * 32767) representing the current position of the axis. It may be necessary - * to impose certain tolerances on these values to account for jitter. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param axis the axis to query; the axis indices start at index 0. - * \returns a 16-bit signed integer representing the current position of the - * axis or 0 on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickNumAxes - */ -extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, - int axis); - -/** - * Get the initial state of an axis control on a joystick. - * - * The state is a value ranging from -32768 to 32767. - * - * The axis indices start at index 0. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param axis the axis to query; the axis indices start at index 0. - * \param state Upon return, the initial value is supplied here. - * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick, - int axis, Sint16 *state); - -/** - * \name Hat positions - */ -/* @{ */ -#define SDL_HAT_CENTERED 0x00 -#define SDL_HAT_UP 0x01 -#define SDL_HAT_RIGHT 0x02 -#define SDL_HAT_DOWN 0x04 -#define SDL_HAT_LEFT 0x08 -#define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) -#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) -#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) -#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) -/* @} */ - -/** - * Get the current state of a POV hat on a joystick. - * - * The returned value will be one of the following positions: - * - * - `SDL_HAT_CENTERED` - * - `SDL_HAT_UP` - * - `SDL_HAT_RIGHT` - * - `SDL_HAT_DOWN` - * - `SDL_HAT_LEFT` - * - `SDL_HAT_RIGHTUP` - * - `SDL_HAT_RIGHTDOWN` - * - `SDL_HAT_LEFTUP` - * - `SDL_HAT_LEFTDOWN` - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param hat the hat index to get the state from; indices start at index 0. - * \returns the current hat position. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickNumHats - */ -extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, - int hat); - -/** - * Get the ball axis change since the last poll. - * - * Trackballs can only return relative motion since the last call to - * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`. - * - * Most joysticks do not have trackballs. - * - * \param joystick the SDL_Joystick to query. - * \param ball the ball index to query; ball indices start at index 0. - * \param dx stores the difference in the x axis position since the last poll. - * \param dy stores the difference in the y axis position since the last poll. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickNumBalls - */ -extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, - int ball, int *dx, int *dy); - -/** - * Get the current state of a button on a joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param button the button index to get the state from; indices start at - * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickNumButtons - */ -extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, - int button); - -/** - * Start a rumble effect. - * - * Each call to this function cancels any previous rumble effect, and calling - * it with 0 intensity stops any rumbling. - * - * \param joystick The joystick to vibrate. - * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF. - * \param high_frequency_rumble The intensity of the high frequency (right) - * rumble motor, from 0 to 0xFFFF. - * \param duration_ms The duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if rumble isn't supported on this joystick. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_JoystickHasRumble - */ -extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); - -/** - * Start a rumble effect in the joystick's triggers - * - * Each call to this function cancels any previous trigger rumble effect, and - * calling it with 0 intensity stops any rumbling. - * - * Note that this is rumbling of the _triggers_ and not the game controller as - * a whole. This is currently only supported on Xbox One controllers. If you - * want the (more common) whole-controller rumble, use SDL_JoystickRumble() - * instead. - * - * \param joystick The joystick to vibrate. - * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF. - * \param right_rumble The intensity of the right trigger rumble motor, from 0 - * to 0xFFFF. - * \param duration_ms The duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if trigger rumble isn't supported on this joystick. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_JoystickHasRumbleTriggers - */ -extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); - -/** - * Query whether a joystick has an LED. - * - * An example of a joystick LED is the light on the back of a PlayStation 4's - * DualShock 4 controller. - * - * \param joystick The joystick to query. - * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick); - -/** - * Query whether a joystick has rumble support. - * - * \param joystick The joystick to query. - * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_JoystickRumble - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick); - -/** - * Query whether a joystick has rumble support on triggers. - * - * \param joystick The joystick to query. - * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_JoystickRumbleTriggers - */ -extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joystick); - -/** - * Update a joystick's LED color. - * - * An example of a joystick LED is the light on the back of a PlayStation 4's - * DualShock 4 controller. - * - * \param joystick The joystick to update. - * \param red The intensity of the red LED. - * \param green The intensity of the green LED. - * \param blue The intensity of the blue LED. - * \returns 0 on success, -1 if this joystick does not have a modifiable LED. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); - -/** - * Send a joystick specific effect packet - * - * \param joystick The joystick to affect. - * \param data The data to send to the joystick. - * \param size The size of the data to send to the joystick. - * \returns 0, or -1 if this joystick or driver doesn't support effect - * packets. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const void *data, int size); - -/** - * Close a joystick previously opened with SDL_JoystickOpen(). - * - * \param joystick The joystick device to close. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_JoystickOpen - */ -extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); - -/** - * Get the battery level of a joystick as SDL_JoystickPowerLevel. - * - * \param joystick the SDL_Joystick to query. - * \returns the current battery level as SDL_JoystickPowerLevel on success or - * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown. - * - * \since This function is available since SDL 2.0.4. - */ -extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_joystick_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_keyboard.h b/code/thirdparty/SDL2-2.32.8/include/SDL_keyboard.h deleted file mode 100644 index 62ac9f2288..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_keyboard.h +++ /dev/null @@ -1,361 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryKeyboard - * - * Include file for SDL keyboard event handling - */ - -#ifndef SDL_keyboard_h_ -#define SDL_keyboard_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_keycode.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * The SDL keysym structure, used in key events. - * - * If you are looking for translated character input, see the SDL_TEXTINPUT - * event. - */ -typedef struct SDL_Keysym -{ - SDL_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */ - SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */ - Uint16 mod; /**< current key modifiers */ - Uint32 unused; -} SDL_Keysym; - -/* Function prototypes */ - -/** - * Query the window which currently has keyboard focus. - * - * \returns the window with keyboard focus. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); - -/** - * Get a snapshot of the current state of the keyboard. - * - * The pointer returned is a pointer to an internal SDL array. It will be - * valid for the whole lifetime of the application and should not be freed by - * the caller. - * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. - * - * Use SDL_PumpEvents() to update the state array. - * - * This function gives you the current state after all events have been - * processed, so if a key or button has been pressed and released before you - * process events, then the pressed state will never show up in the - * SDL_GetKeyboardState() calls. - * - * Note: This function doesn't take into account whether shift has been - * pressed or not. - * - * \param numkeys if non-NULL, receives the length of the returned array. - * \returns a pointer to an array of key states. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PumpEvents - * \sa SDL_ResetKeyboard - */ -extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys); - -/** - * Clear the state of the keyboard - * - * This function will generate key up events for all pressed keys. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GetKeyboardState - */ -extern DECLSPEC void SDLCALL SDL_ResetKeyboard(void); - -/** - * Get the current key modifier state for the keyboard. - * - * \returns an OR'd combination of the modifier keys for the keyboard. See - * SDL_Keymod for details. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyboardState - * \sa SDL_SetModState - */ -extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); - -/** - * Set the current key modifier state for the keyboard. - * - * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose - * modifier key states on your application. Simply pass your desired modifier - * states into `modstate`. This value may be a bitwise, OR'd combination of - * SDL_Keymod values. - * - * This does not change the keyboard state, only the key modifier flags that - * SDL reports. - * - * \param modstate the desired SDL_Keymod for the keyboard. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetModState - */ -extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); - -/** - * Get the key code corresponding to the given scancode according to the - * current keyboard layout. - * - * See SDL_Keycode for details. - * - * \param scancode the desired SDL_Scancode to query. - * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyName - * \sa SDL_GetScancodeFromKey - */ -extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode); - -/** - * Get the scancode corresponding to the given key code according to the - * current keyboard layout. - * - * See SDL_Scancode for details. - * - * \param key the desired SDL_Keycode to query. - * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyFromScancode - * \sa SDL_GetScancodeName - */ -extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key); - -/** - * Get a human-readable name for a scancode. - * - * See SDL_Scancode for details. - * - * **Warning**: The returned name is by design not stable across platforms, - * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left - * Windows" under Microsoft Windows, and some scancodes like - * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even - * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and - * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore - * unsuitable for creating a stable cross-platform two-way mapping between - * strings and scancodes. - * - * \param scancode the desired SDL_Scancode to query. - * \returns a pointer to the name for the scancode. If the scancode doesn't - * have a name this function returns an empty string (""). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetScancodeFromKey - * \sa SDL_GetScancodeFromName - */ -extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); - -/** - * Get a scancode from a human-readable name. - * - * \param name the human-readable scancode name. - * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't - * recognized; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyFromName - * \sa SDL_GetScancodeFromKey - * \sa SDL_GetScancodeName - */ -extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); - -/** - * Get a human-readable name for a key. - * - * See SDL_Scancode and SDL_Keycode for details. - * - * \param key the desired SDL_Keycode to query. - * \returns a pointer to a UTF-8 string that stays valid at least until the - * next call to this function. If you need it around any longer, you - * must copy it. If the key doesn't have a name, this function - * returns an empty string (""). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyFromName - * \sa SDL_GetKeyFromScancode - * \sa SDL_GetScancodeFromKey - */ -extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key); - -/** - * Get a key code from a human-readable name. - * - * \param name the human-readable key name. - * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetKeyFromScancode - * \sa SDL_GetKeyName - * \sa SDL_GetScancodeFromName - */ -extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); - -/** - * Start accepting Unicode text input events. - * - * This function will start accepting Unicode text input events in the focused - * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and - * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in - * pair with SDL_StopTextInput(). - * - * On some platforms using this function activates the screen keyboard. - * - * On desktop platforms, SDL_StartTextInput() is implicitly called on SDL - * video subsystem initialization which will cause SDL_TextInputEvent and - * SDL_TextEditingEvent to begin emitting. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetTextInputRect - * \sa SDL_StopTextInput - */ -extern DECLSPEC void SDLCALL SDL_StartTextInput(void); - -/** - * Check whether or not Unicode text input events are enabled. - * - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_StartTextInput - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void); - -/** - * Stop receiving any text input events. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_StartTextInput - */ -extern DECLSPEC void SDLCALL SDL_StopTextInput(void); - -/** - * Dismiss the composition window/IME without disabling the subsystem. - * - * \since This function is available since SDL 2.0.22. - * - * \sa SDL_StartTextInput - * \sa SDL_StopTextInput - */ -extern DECLSPEC void SDLCALL SDL_ClearComposition(void); - -/** - * Returns if an IME Composite or Candidate window is currently shown. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); - -/** - * Set the rectangle used to type Unicode text inputs. - * - * Native input methods will place a window with word suggestions near it, - * without covering the text being inputted. - * - * To start text input in a given location, this function is intended to be - * called before SDL_StartTextInput, although some platforms support moving - * the rectangle even while text input (and a composition) is active. - * - * Note: If you want to use the system native IME window, try setting hint - * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you - * any feedback. - * - * \param rect the SDL_Rect structure representing the rectangle to receive - * text (ignored if NULL). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_StartTextInput - */ -extern DECLSPEC void SDLCALL SDL_SetTextInputRect(const SDL_Rect *rect); - -/** - * Check whether the platform has screen keyboard support. - * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_StartTextInput - * \sa SDL_IsScreenKeyboardShown - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); - -/** - * Check whether the screen keyboard is shown for given window. - * - * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasScreenKeyboardSupport - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_keyboard_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_keycode.h b/code/thirdparty/SDL2-2.32.8/include/SDL_keycode.h deleted file mode 100644 index eb1678e386..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_keycode.h +++ /dev/null @@ -1,358 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryKeycode - * - * Defines constants which identify keyboard keys and modifiers. - */ - -#ifndef SDL_keycode_h_ -#define SDL_keycode_h_ - -#include "SDL_stdinc.h" -#include "SDL_scancode.h" - -/** - * The SDL virtual key representation. - * - * Values of this type are used to represent keyboard keys using the current - * layout of the keyboard. These values include Unicode values representing - * the unmodified character that would be generated by pressing the key, or an - * SDLK_* constant for those keys that do not generate characters. - * - * A special exception is the number keys at the top of the keyboard which map - * to SDLK_0...SDLK_9 on AZERTY layouts. - */ -typedef Sint32 SDL_Keycode; - -#define SDLK_SCANCODE_MASK (1<<30) -#define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) - -typedef enum SDL_KeyCode -{ - SDLK_UNKNOWN = 0, - - SDLK_RETURN = '\r', - SDLK_ESCAPE = '\x1B', - SDLK_BACKSPACE = '\b', - SDLK_TAB = '\t', - SDLK_SPACE = ' ', - SDLK_EXCLAIM = '!', - SDLK_QUOTEDBL = '"', - SDLK_HASH = '#', - SDLK_PERCENT = '%', - SDLK_DOLLAR = '$', - SDLK_AMPERSAND = '&', - SDLK_QUOTE = '\'', - SDLK_LEFTPAREN = '(', - SDLK_RIGHTPAREN = ')', - SDLK_ASTERISK = '*', - SDLK_PLUS = '+', - SDLK_COMMA = ',', - SDLK_MINUS = '-', - SDLK_PERIOD = '.', - SDLK_SLASH = '/', - SDLK_0 = '0', - SDLK_1 = '1', - SDLK_2 = '2', - SDLK_3 = '3', - SDLK_4 = '4', - SDLK_5 = '5', - SDLK_6 = '6', - SDLK_7 = '7', - SDLK_8 = '8', - SDLK_9 = '9', - SDLK_COLON = ':', - SDLK_SEMICOLON = ';', - SDLK_LESS = '<', - SDLK_EQUALS = '=', - SDLK_GREATER = '>', - SDLK_QUESTION = '?', - SDLK_AT = '@', - - /* - Skip uppercase letters - */ - - SDLK_LEFTBRACKET = '[', - SDLK_BACKSLASH = '\\', - SDLK_RIGHTBRACKET = ']', - SDLK_CARET = '^', - SDLK_UNDERSCORE = '_', - SDLK_BACKQUOTE = '`', - SDLK_a = 'a', - SDLK_b = 'b', - SDLK_c = 'c', - SDLK_d = 'd', - SDLK_e = 'e', - SDLK_f = 'f', - SDLK_g = 'g', - SDLK_h = 'h', - SDLK_i = 'i', - SDLK_j = 'j', - SDLK_k = 'k', - SDLK_l = 'l', - SDLK_m = 'm', - SDLK_n = 'n', - SDLK_o = 'o', - SDLK_p = 'p', - SDLK_q = 'q', - SDLK_r = 'r', - SDLK_s = 's', - SDLK_t = 't', - SDLK_u = 'u', - SDLK_v = 'v', - SDLK_w = 'w', - SDLK_x = 'x', - SDLK_y = 'y', - SDLK_z = 'z', - - SDLK_CAPSLOCK = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK), - - SDLK_F1 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1), - SDLK_F2 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2), - SDLK_F3 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3), - SDLK_F4 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4), - SDLK_F5 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5), - SDLK_F6 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6), - SDLK_F7 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7), - SDLK_F8 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8), - SDLK_F9 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9), - SDLK_F10 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10), - SDLK_F11 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11), - SDLK_F12 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12), - - SDLK_PRINTSCREEN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN), - SDLK_SCROLLLOCK = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK), - SDLK_PAUSE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE), - SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT), - SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME), - SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP), - SDLK_DELETE = '\x7F', - SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END), - SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN), - SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT), - SDLK_LEFT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT), - SDLK_DOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN), - SDLK_UP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP), - - SDLK_NUMLOCKCLEAR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR), - SDLK_KP_DIVIDE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE), - SDLK_KP_MULTIPLY = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY), - SDLK_KP_MINUS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS), - SDLK_KP_PLUS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS), - SDLK_KP_ENTER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER), - SDLK_KP_1 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1), - SDLK_KP_2 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2), - SDLK_KP_3 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3), - SDLK_KP_4 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4), - SDLK_KP_5 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5), - SDLK_KP_6 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6), - SDLK_KP_7 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7), - SDLK_KP_8 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8), - SDLK_KP_9 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9), - SDLK_KP_0 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0), - SDLK_KP_PERIOD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD), - - SDLK_APPLICATION = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION), - SDLK_POWER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER), - SDLK_KP_EQUALS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS), - SDLK_F13 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13), - SDLK_F14 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14), - SDLK_F15 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15), - SDLK_F16 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16), - SDLK_F17 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17), - SDLK_F18 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18), - SDLK_F19 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19), - SDLK_F20 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20), - SDLK_F21 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21), - SDLK_F22 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22), - SDLK_F23 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23), - SDLK_F24 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24), - SDLK_EXECUTE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE), - SDLK_HELP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP), - SDLK_MENU = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU), - SDLK_SELECT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT), - SDLK_STOP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP), - SDLK_AGAIN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN), - SDLK_UNDO = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO), - SDLK_CUT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT), - SDLK_COPY = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY), - SDLK_PASTE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE), - SDLK_FIND = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND), - SDLK_MUTE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE), - SDLK_VOLUMEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP), - SDLK_VOLUMEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN), - SDLK_KP_COMMA = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA), - SDLK_KP_EQUALSAS400 = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400), - - SDLK_ALTERASE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE), - SDLK_SYSREQ = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ), - SDLK_CANCEL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL), - SDLK_CLEAR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR), - SDLK_PRIOR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR), - SDLK_RETURN2 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2), - SDLK_SEPARATOR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR), - SDLK_OUT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT), - SDLK_OPER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER), - SDLK_CLEARAGAIN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN), - SDLK_CRSEL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL), - SDLK_EXSEL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL), - - SDLK_KP_00 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00), - SDLK_KP_000 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000), - SDLK_THOUSANDSSEPARATOR = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR), - SDLK_DECIMALSEPARATOR = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR), - SDLK_CURRENCYUNIT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT), - SDLK_CURRENCYSUBUNIT = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT), - SDLK_KP_LEFTPAREN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN), - SDLK_KP_RIGHTPAREN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN), - SDLK_KP_LEFTBRACE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE), - SDLK_KP_RIGHTBRACE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE), - SDLK_KP_TAB = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB), - SDLK_KP_BACKSPACE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE), - SDLK_KP_A = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A), - SDLK_KP_B = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B), - SDLK_KP_C = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C), - SDLK_KP_D = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D), - SDLK_KP_E = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E), - SDLK_KP_F = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F), - SDLK_KP_XOR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR), - SDLK_KP_POWER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER), - SDLK_KP_PERCENT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT), - SDLK_KP_LESS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS), - SDLK_KP_GREATER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER), - SDLK_KP_AMPERSAND = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND), - SDLK_KP_DBLAMPERSAND = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND), - SDLK_KP_VERTICALBAR = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR), - SDLK_KP_DBLVERTICALBAR = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR), - SDLK_KP_COLON = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON), - SDLK_KP_HASH = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH), - SDLK_KP_SPACE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE), - SDLK_KP_AT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT), - SDLK_KP_EXCLAM = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM), - SDLK_KP_MEMSTORE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE), - SDLK_KP_MEMRECALL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL), - SDLK_KP_MEMCLEAR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR), - SDLK_KP_MEMADD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD), - SDLK_KP_MEMSUBTRACT = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT), - SDLK_KP_MEMMULTIPLY = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY), - SDLK_KP_MEMDIVIDE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE), - SDLK_KP_PLUSMINUS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS), - SDLK_KP_CLEAR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR), - SDLK_KP_CLEARENTRY = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY), - SDLK_KP_BINARY = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY), - SDLK_KP_OCTAL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL), - SDLK_KP_DECIMAL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL), - SDLK_KP_HEXADECIMAL = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL), - - SDLK_LCTRL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL), - SDLK_LSHIFT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT), - SDLK_LALT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT), - SDLK_LGUI = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI), - SDLK_RCTRL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL), - SDLK_RSHIFT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT), - SDLK_RALT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT), - SDLK_RGUI = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI), - - SDLK_MODE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE), - - SDLK_AUDIONEXT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIONEXT), - SDLK_AUDIOPREV = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOPREV), - SDLK_AUDIOSTOP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOSTOP), - SDLK_AUDIOPLAY = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOPLAY), - SDLK_AUDIOMUTE = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOMUTE), - SDLK_MEDIASELECT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIASELECT), - SDLK_WWW = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WWW), - SDLK_MAIL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MAIL), - SDLK_CALCULATOR = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALCULATOR), - SDLK_COMPUTER = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COMPUTER), - SDLK_AC_SEARCH = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH), - SDLK_AC_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME), - SDLK_AC_BACK = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK), - SDLK_AC_FORWARD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD), - SDLK_AC_STOP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP), - SDLK_AC_REFRESH = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH), - SDLK_AC_BOOKMARKS = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS), - - SDLK_BRIGHTNESSDOWN = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_BRIGHTNESSDOWN), - SDLK_BRIGHTNESSUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_BRIGHTNESSUP), - SDLK_DISPLAYSWITCH = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DISPLAYSWITCH), - SDLK_KBDILLUMTOGGLE = - SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KBDILLUMTOGGLE), - SDLK_KBDILLUMDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KBDILLUMDOWN), - SDLK_KBDILLUMUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KBDILLUMUP), - SDLK_EJECT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EJECT), - SDLK_SLEEP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP), - SDLK_APP1 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APP1), - SDLK_APP2 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APP2), - - SDLK_AUDIOREWIND = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOREWIND), - SDLK_AUDIOFASTFORWARD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOFASTFORWARD), - - SDLK_SOFTLEFT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT), - SDLK_SOFTRIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT), - SDLK_CALL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL), - SDLK_ENDCALL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) -} SDL_KeyCode; - -/** - * Enumeration of valid key mods (possibly OR'd together). - */ -typedef enum SDL_Keymod -{ - KMOD_NONE = 0x0000, - KMOD_LSHIFT = 0x0001, - KMOD_RSHIFT = 0x0002, - KMOD_LCTRL = 0x0040, - KMOD_RCTRL = 0x0080, - KMOD_LALT = 0x0100, - KMOD_RALT = 0x0200, - KMOD_LGUI = 0x0400, - KMOD_RGUI = 0x0800, - KMOD_NUM = 0x1000, - KMOD_CAPS = 0x2000, - KMOD_MODE = 0x4000, - KMOD_SCROLL = 0x8000, - - KMOD_CTRL = KMOD_LCTRL | KMOD_RCTRL, - KMOD_SHIFT = KMOD_LSHIFT | KMOD_RSHIFT, - KMOD_ALT = KMOD_LALT | KMOD_RALT, - KMOD_GUI = KMOD_LGUI | KMOD_RGUI, - - KMOD_RESERVED = KMOD_SCROLL /* This is for source-level compatibility with SDL 2.0.0. */ -} SDL_Keymod; - -#endif /* SDL_keycode_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_log.h b/code/thirdparty/SDL2-2.32.8/include/SDL_log.h deleted file mode 100644 index 75833ba3c3..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_log.h +++ /dev/null @@ -1,405 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryLog - * - * Simple log messages with categories and priorities. - * - * By default logs are quiet, but if you're debugging SDL you might want: - * - * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); - * - * Here's where the messages go on different platforms: - * - * - Windows: debug output stream - * - Android: log output - * - Others: standard error output (stderr) - */ - -#ifndef SDL_log_h_ -#define SDL_log_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - - -/** - * The maximum size of a log message prior to SDL 2.0.24 - * - * As of 2.0.24 there is no limit to the length of SDL log messages. - */ -#define SDL_MAX_LOG_MESSAGE 4096 - -/** - * The predefined log categories - * - * By default the application category is enabled at the INFO level, the - * assert category is enabled at the WARN level, test is enabled at the - * VERBOSE level and all other categories are enabled at the ERROR level. - */ -typedef enum SDL_LogCategory -{ - SDL_LOG_CATEGORY_APPLICATION, - SDL_LOG_CATEGORY_ERROR, - SDL_LOG_CATEGORY_ASSERT, - SDL_LOG_CATEGORY_SYSTEM, - SDL_LOG_CATEGORY_AUDIO, - SDL_LOG_CATEGORY_VIDEO, - SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_INPUT, - SDL_LOG_CATEGORY_TEST, - - /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, - SDL_LOG_CATEGORY_RESERVED2, - SDL_LOG_CATEGORY_RESERVED3, - SDL_LOG_CATEGORY_RESERVED4, - SDL_LOG_CATEGORY_RESERVED5, - SDL_LOG_CATEGORY_RESERVED6, - SDL_LOG_CATEGORY_RESERVED7, - SDL_LOG_CATEGORY_RESERVED8, - SDL_LOG_CATEGORY_RESERVED9, - SDL_LOG_CATEGORY_RESERVED10, - - /* Beyond this point is reserved for application use, e.g. - enum { - MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM, - MYAPP_CATEGORY_AWESOME2, - MYAPP_CATEGORY_AWESOME3, - ... - }; - */ - SDL_LOG_CATEGORY_CUSTOM -} SDL_LogCategory; - -/** - * The predefined log priorities - */ -typedef enum SDL_LogPriority -{ - SDL_LOG_PRIORITY_VERBOSE = 1, - SDL_LOG_PRIORITY_DEBUG, - SDL_LOG_PRIORITY_INFO, - SDL_LOG_PRIORITY_WARN, - SDL_LOG_PRIORITY_ERROR, - SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES -} SDL_LogPriority; - - -/** - * Set the priority of all log categories. - * - * \param priority the SDL_LogPriority to assign. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogSetPriority - */ -extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority); - -/** - * Set the priority of a particular log category. - * - * \param category the category to assign a priority to. - * \param priority the SDL_LogPriority to assign. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogGetPriority - * \sa SDL_LogSetAllPriority - */ -extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category, - SDL_LogPriority priority); - -/** - * Get the priority of a particular log category. - * - * \param category the category to query. - * \returns the SDL_LogPriority for the requested category. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogSetPriority - */ -extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category); - -/** - * Reset all priorities to default. - * - * This is called by SDL_Quit(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogSetAllPriority - * \sa SDL_LogSetPriority - */ -extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void); - -/** - * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. - * - * = * \param fmt a printf() style message format string - * - * \param ... additional parameters matching % tokens in the `fmt` string, if - * any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); - -/** - * Log a message with SDL_LOG_PRIORITY_VERBOSE. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with SDL_LOG_PRIORITY_DEBUG. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with SDL_LOG_PRIORITY_INFO. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with SDL_LOG_PRIORITY_WARN. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - */ -extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with SDL_LOG_PRIORITY_ERROR. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with SDL_LOG_PRIORITY_CRITICAL. - * - * \param category the category of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); - -/** - * Log a message with the specified category and priority. - * - * \param category the category of the message. - * \param priority the priority of the message. - * \param fmt a printf() style message format string. - * \param ... additional parameters matching % tokens in the **fmt** string, - * if any. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessageV - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogMessage(int category, - SDL_LogPriority priority, - SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); - -/** - * Log a message with the specified category and priority. - * - * \param category the category of the message. - * \param priority the priority of the message. - * \param fmt a printf() style message format string. - * \param ap a variable argument list. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Log - * \sa SDL_LogCritical - * \sa SDL_LogDebug - * \sa SDL_LogError - * \sa SDL_LogInfo - * \sa SDL_LogMessage - * \sa SDL_LogVerbose - * \sa SDL_LogWarn - */ -extern DECLSPEC void SDLCALL SDL_LogMessageV(int category, - SDL_LogPriority priority, - SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); - -/** - * The prototype for the log output callback function. - * - * This function is called by SDL when there is new text to be logged. - * - * \param userdata what was passed as `userdata` to - * SDL_LogSetOutputFunction(). - * \param category the category of the message. - * \param priority the priority of the message. - * \param message the message being output. - */ -typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); - -/** - * Get the current log output function. - * - * \param callback an SDL_LogOutputFunction filled in with the current log - * callback. - * \param userdata a pointer filled in with the pointer that is passed to - * `callback`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogSetOutputFunction - */ -extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata); - -/** - * Replace the default log output function with one of your own. - * - * \param callback an SDL_LogOutputFunction to call instead of the default. - * \param userdata a pointer that is passed to `callback`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LogGetOutputFunction - */ -extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_log_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_main.h b/code/thirdparty/SDL2-2.32.8/include/SDL_main.h deleted file mode 100644 index a1ef3e7464..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_main.h +++ /dev/null @@ -1,282 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_main_h_ -#define SDL_main_h_ - -#include "SDL_stdinc.h" - -/** - * # CategoryMain - * - * Redefine main() on some platforms so that it is called by SDL. - */ - -#ifndef SDL_MAIN_HANDLED -#if defined(__WIN32__) -/* On Windows SDL provides WinMain(), which parses the command line and passes - the arguments to your main function. - - If you provide your own WinMain(), you may define SDL_MAIN_HANDLED - */ -#define SDL_MAIN_AVAILABLE - -#elif defined(__WINRT__) -/* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - Please note that #include'ing SDL_main.h is not enough to get a main() - function working. In non-XAML apps, the file, - src/main/winrt/SDL_WinRT_main_NonXAML.cpp, or a copy of it, must be compiled - into the app itself. In XAML apps, the function, SDL_WinRTRunApp must be - called, with a pointer to the Direct3D-hosted XAML control passed in. -*/ -#define SDL_MAIN_NEEDED - -#elif defined(__GDK__) -/* On GDK, SDL provides a main function that initializes the game runtime. - - Please note that #include'ing SDL_main.h is not enough to get a main() - function working. You must either link against SDL2main or, if not possible, - call the SDL_GDKRunApp function from your entry point. -*/ -#define SDL_MAIN_NEEDED - -#elif defined(__IPHONEOS__) -/* On iOS SDL provides a main function that creates an application delegate - and starts the iOS application run loop. - - If you link with SDL dynamically on iOS, the main function can't be in a - shared library, so you need to link with libSDLmain.a, which includes a - stub main function that calls into the shared library to start execution. - - See src/video/uikit/SDL_uikitappdelegate.m for more details. - */ -#define SDL_MAIN_NEEDED - -#elif defined(__ANDROID__) -/* On Android SDL provides a Java class in SDLActivity.java that is the - main activity entry point. - - See docs/README-android.md for more details on extending that class. - */ -#define SDL_MAIN_NEEDED - -/* We need to export SDL_main so it can be launched from Java */ -#define SDLMAIN_DECLSPEC DECLSPEC - -#elif defined(__NACL__) -/* On NACL we use ppapi_simple to set up the application helper code, - then wait for the first PSE_INSTANCE_DIDCHANGEVIEW event before - starting the user main function. - All user code is run in a separate thread by ppapi_simple, thus - allowing for blocking io to take place via nacl_io -*/ -#define SDL_MAIN_NEEDED - -#elif defined(__PSP__) -/* On PSP SDL provides a main function that sets the module info, - activates the GPU and starts the thread required to be able to exit - the software. - - If you provide this yourself, you may define SDL_MAIN_HANDLED - */ -#define SDL_MAIN_AVAILABLE - -#elif defined(__PS2__) -#define SDL_MAIN_AVAILABLE - -#define SDL_PS2_SKIP_IOP_RESET() \ - void reset_IOP(); \ - void reset_IOP() {} - -#elif defined(__3DS__) -/* - On N3DS, SDL provides a main function that sets up the screens - and storage. - - If you provide this yourself, you may define SDL_MAIN_HANDLED -*/ -#define SDL_MAIN_AVAILABLE - -#endif -#endif /* SDL_MAIN_HANDLED */ - -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ - -#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) -#define main SDL_main -#endif - -#include "begin_code.h" -#ifdef __cplusplus -extern "C" { -#endif - -/** - * The prototype for the application's main() function - */ -typedef int (*SDL_main_func)(int argc, char *argv[]); -extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]); - - -/** - * Circumvent failure of SDL_Init() when not using SDL_main() as an entry - * point. - * - * This function is defined in SDL_main.h, along with the preprocessor rule to - * redefine main() as SDL_main(). Thus to ensure that your main() function - * will not be changed it is necessary to define SDL_MAIN_HANDLED before - * including SDL.h. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_Init - */ -extern DECLSPEC void SDLCALL SDL_SetMainReady(void); - -#if defined(__WIN32__) || defined(__GDK__) - -/** - * Register a win32 window class for SDL's use. - * - * This can be called to set the application window class at startup. It is - * safe to call this multiple times, as long as every call is eventually - * paired with a call to SDL_UnregisterApp, but a second registration attempt - * while a previous registration is still active will be ignored, other than - * to increment a counter. - * - * Most applications do not need to, and should not, call this directly; SDL - * will call it when initializing the video subsystem. - * - * \param name the window class name, in UTF-8 encoding. If NULL, SDL - * currently uses "SDL_app" but this isn't guaranteed. - * \param style the value to use in WNDCLASSEX::style. If `name` is NULL, SDL - * currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` regardless of - * what is specified here. - * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL - * will use `GetModuleHandle(NULL)` instead. - * \returns 0 on success, -1 on error. SDL_GetError() may have details. - * - * \since This function is available since SDL 2.0.2. - */ -extern DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); - -/** - * Deregister the win32 window class from an SDL_RegisterApp call. - * - * This can be called to undo the effects of SDL_RegisterApp. - * - * Most applications do not need to, and should not, call this directly; SDL - * will call it when deinitializing the video subsystem. - * - * It is safe to call this multiple times, as long as every call is eventually - * paired with a prior call to SDL_RegisterApp. The window class will only be - * deregistered when the registration counter in SDL_RegisterApp decrements to - * zero through calls to this function. - * - * \since This function is available since SDL 2.0.2. - */ -extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); - -#endif /* defined(__WIN32__) || defined(__GDK__) */ - - -#ifdef __WINRT__ - -/** - * Initialize and launch an SDL/WinRT application. - * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func. - * \param reserved reserved for future use; should be NULL. - * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve - * more information on the failure. - * - * \since This function is available since SDL 2.0.3. - */ -extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved); - -#endif /* __WINRT__ */ - -#if defined(__IPHONEOS__) - -/** - * Initializes and launches an SDL application. - * - * \param argc The argc parameter from the application's main() function. - * \param argv The argv parameter from the application's main() function. - * \param mainFunction The SDL app's C-style main(), an SDL_main_func. - * \return the return value from mainFunction. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction); - -#endif /* __IPHONEOS__ */ - -#ifdef __GDK__ - -/** - * Initialize and launch an SDL GDK application. - * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func. - * \param reserved reserved for future use; should be NULL. - * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve - * more information on the failure. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC int SDLCALL SDL_GDKRunApp(SDL_main_func mainFunction, void *reserved); - -/** - * Callback from the application to let the suspend continue. - * - * \since This function is available since SDL 2.28.0. - */ -extern DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); - -#endif /* __GDK__ */ - -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_main_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_mouse.h b/code/thirdparty/SDL2-2.32.8/include/SDL_mouse.h deleted file mode 100644 index 628b7a2f83..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_mouse.h +++ /dev/null @@ -1,464 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryMouse - * - * Include file for SDL mouse event handling. - */ - -#ifndef SDL_mouse_h_ -#define SDL_mouse_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ - -/** - * Cursor types for SDL_CreateSystemCursor(). - */ -typedef enum SDL_SystemCursor -{ - SDL_SYSTEM_CURSOR_ARROW, /**< Arrow */ - SDL_SYSTEM_CURSOR_IBEAM, /**< I-beam */ - SDL_SYSTEM_CURSOR_WAIT, /**< Wait */ - SDL_SYSTEM_CURSOR_CROSSHAIR, /**< Crosshair */ - SDL_SYSTEM_CURSOR_WAITARROW, /**< Small wait cursor (or Wait if not available) */ - SDL_SYSTEM_CURSOR_SIZENWSE, /**< Double arrow pointing northwest and southeast */ - SDL_SYSTEM_CURSOR_SIZENESW, /**< Double arrow pointing northeast and southwest */ - SDL_SYSTEM_CURSOR_SIZEWE, /**< Double arrow pointing west and east */ - SDL_SYSTEM_CURSOR_SIZENS, /**< Double arrow pointing north and south */ - SDL_SYSTEM_CURSOR_SIZEALL, /**< Four pointed arrow pointing north, south, east, and west */ - SDL_SYSTEM_CURSOR_NO, /**< Slashed circle or crossbones */ - SDL_SYSTEM_CURSOR_HAND, /**< Hand */ - SDL_NUM_SYSTEM_CURSORS -} SDL_SystemCursor; - -/** - * Scroll direction types for the Scroll event - */ -typedef enum SDL_MouseWheelDirection -{ - SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */ - SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */ -} SDL_MouseWheelDirection; - -/* Function prototypes */ - -/** - * Get the window which currently has mouse focus. - * - * \returns the window with mouse focus. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); - -/** - * Retrieve the current state of the mouse. - * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. - * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetGlobalMouseState - * \sa SDL_GetRelativeMouseState - * \sa SDL_PumpEvents - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y); - -/** - * Get the current state of the mouse in relation to the desktop. - * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. - * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. - * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_CaptureMouse - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y); - -/** - * Retrieve the relative state of the mouse. - * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. - * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetMouseState - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y); - -/** - * Move the mouse cursor to the given position within the window. - * - * This function generates a mouse motion event if relative mode is not - * enabled. If relative mode is enabled, you can force mouse events for the - * warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint. - * - * Note that this function will appear to succeed, but not actually move the - * mouse when used over Microsoft Remote Desktop. - * - * \param window the window to move the mouse into, or NULL for the current - * mouse focus. - * \param x the x coordinate within the window. - * \param y the y coordinate within the window. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WarpMouseGlobal - */ -extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, - int x, int y); - -/** - * Move the mouse to the given position in global screen space. - * - * This function generates a mouse motion event. - * - * A failure of this function usually means that it is unsupported by a - * platform. - * - * Note that this function will appear to succeed, but not actually move the - * mouse when used over Microsoft Remote Desktop. - * - * \param x the x coordinate. - * \param y the y coordinate. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_WarpMouseInWindow - */ -extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y); - -/** - * Set relative mouse mode. - * - * While the mouse is in relative mode, the cursor is hidden, the mouse - * position is constrained to the window, and SDL will report continuous - * relative mouse motion even if the mouse is at the edge of the window. - * - * This function will flush any pending mouse motion. - * - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * If relative mode is not supported, this returns -1. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRelativeMouseMode - */ -extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled); - -/** - * Capture the mouse and to track input outside an SDL window. - * - * Capturing enables your app to obtain mouse events globally, instead of just - * within your window. Not all video targets support this function. When - * capturing is enabled, the current window will get all mouse events, but - * unlike relative mode, no change is made to the cursor and it is not - * restrained to your window. - * - * This function may also deny mouse input to other windows--both those in - * your application and others on the system--so you should use this function - * sparingly, and in small bursts. For example, you might want to track the - * mouse while the user is dragging something, until the user releases a mouse - * button. It is not recommended that you capture the mouse for long periods - * of time, such as the entire time your app is running. For that, you should - * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending - * on your goals. - * - * While captured, mouse events still report coordinates relative to the - * current (foreground) window, but those coordinates may be outside the - * bounds of the window (including negative values). Capturing is only allowed - * for the foreground window. If the window loses focus while capturing, the - * capture will be disabled automatically. - * - * While capturing is enabled, the current window will have the - * `SDL_WINDOW_MOUSE_CAPTURE` flag set. - * - * Please note that as of SDL 2.0.22, SDL will attempt to "auto capture" the - * mouse while the user is pressing a button; this is to try and make mouse - * behavior more consistent between platforms, and deal with the common case - * of a user dragging the mouse outside of the window. This means that if you - * are calling SDL_CaptureMouse() only to deal with this situation, you no - * longer have to (although it is safe to do so). If this causes problems for - * your app, you can disable auto capture by setting the - * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. - * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns 0 on success or -1 if not supported; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_GetGlobalMouseState - */ -extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled); - -/** - * Query whether relative mouse mode is enabled. - * - * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRelativeMouseMode - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); - -/** - * Create a cursor using the specified bitmap data and mask (in MSB format). - * - * `mask` has to be in MSB (Most Significant Bit) format. - * - * The cursor width (`w`) must be a multiple of 8 bits. - * - * The cursor is created in black and white according to the following: - * - * - data=0, mask=1: white - * - data=1, mask=1: black - * - data=0, mask=0: transparent - * - data=1, mask=0: inverted color if possible, black if not. - * - * Cursors created with this function must be freed with SDL_FreeCursor(). - * - * If you want to have a color cursor, or create your cursor from an - * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can - * hide the cursor and draw your own as part of your game's rendering, but it - * will be bound to the framerate. - * - * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which - * provides twelve readily available system cursors to pick from. - * - * \param data the color value for each pixel of the cursor. - * \param mask the mask value for each pixel of the cursor. - * \param w the width of the cursor. - * \param h the height of the cursor. - * \param hot_x the X-axis location of the upper left corner of the cursor - * relative to the actual mouse position. - * \param hot_y the Y-axis location of the upper left corner of the cursor - * relative to the actual mouse position. - * \returns a new cursor with the specified parameters on success or NULL on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeCursor - * \sa SDL_SetCursor - * \sa SDL_ShowCursor - */ -extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data, - const Uint8 * mask, - int w, int h, int hot_x, - int hot_y); - -/** - * Create a color cursor. - * - * \param surface an SDL_Surface structure representing the cursor image. - * \param hot_x the x position of the cursor hot spot. - * \param hot_y the y position of the cursor hot spot. - * \returns the new cursor on success or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateCursor - * \sa SDL_FreeCursor - */ -extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, - int hot_x, - int hot_y); - -/** - * Create a system cursor. - * - * \param id an SDL_SystemCursor enum value. - * \returns a cursor on success or NULL on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeCursor - */ -extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); - -/** - * Set the active cursor. - * - * This function sets the currently active cursor to the specified one. If the - * cursor is currently visible, the change will be immediately represented on - * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if - * this is desired for any reason. - * - * \param cursor a cursor to make active. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateCursor - * \sa SDL_GetCursor - * \sa SDL_ShowCursor - */ -extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor); - -/** - * Get the active cursor. - * - * This function returns a pointer to the current cursor which is owned by the - * library. It is not necessary to free the cursor with SDL_FreeCursor(). - * - * \returns the active cursor or NULL if there is no mouse. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetCursor - */ -extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void); - -/** - * Get the default cursor. - * - * You do not have to call SDL_FreeCursor() on the return value, but it is - * safe to do so. - * - * \returns the default cursor on success or NULL on failure. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSystemCursor - */ -extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void); - -/** - * Free a previously-created cursor. - * - * Use this function to free cursor resources created with SDL_CreateCursor(), - * SDL_CreateColorCursor() or SDL_CreateSystemCursor(). - * - * \param cursor the cursor to free. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateColorCursor - * \sa SDL_CreateCursor - * \sa SDL_CreateSystemCursor - */ -extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor); - -/** - * Toggle whether or not the cursor is shown. - * - * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE` - * displays the cursor and passing `SDL_DISABLE` hides it. - * - * The current state of the mouse cursor can be queried by passing - * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned. - * - * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it, - * `SDL_QUERY` to query the current state without changing it. - * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the - * cursor is hidden, or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateCursor - * \sa SDL_SetCursor - */ -extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle); - -/** - * Used as a mask when testing buttons in buttonstate. - * - * - Button 1: Left mouse button - * - Button 2: Middle mouse button - * - Button 3: Right mouse button - */ -#define SDL_BUTTON(X) (1 << ((X)-1)) -#define SDL_BUTTON_LEFT 1 -#define SDL_BUTTON_MIDDLE 2 -#define SDL_BUTTON_RIGHT 3 -#define SDL_BUTTON_X1 4 -#define SDL_BUTTON_X2 5 -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_mouse_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_mutex.h b/code/thirdparty/SDL2-2.32.8/include/SDL_mutex.h deleted file mode 100644 index 0fe3eb5a5f..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_mutex.h +++ /dev/null @@ -1,545 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_mutex_h_ -#define SDL_mutex_h_ - -/** - * # CategoryMutex - * - * Functions to provide thread synchronization primitives. - */ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -/******************************************************************************/ -/* Enable thread safety attributes only with clang. - * The attributes can be safely erased when compiling with other compilers. - */ -#if 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 - -#define SDL_CAPABILITY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) - -#define SDL_SCOPED_CAPABILITY \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) - -#define SDL_GUARDED_BY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) - -#define SDL_PT_GUARDED_BY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) - -#define SDL_ACQUIRED_BEFORE(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) - -#define SDL_ACQUIRED_AFTER(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) - -#define SDL_REQUIRES(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) - -#define SDL_REQUIRES_SHARED(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) - -#define SDL_ACQUIRE(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) - -#define SDL_ACQUIRE_SHARED(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) - -#define SDL_RELEASE(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) - -#define SDL_RELEASE_SHARED(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) - -#define SDL_RELEASE_GENERIC(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) - -#define SDL_TRY_ACQUIRE(x, y) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) - -#define SDL_TRY_ACQUIRE_SHARED(x, y) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) - -#define SDL_EXCLUDES(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) - -#define SDL_ASSERT_CAPABILITY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) - -#define SDL_ASSERT_SHARED_CAPABILITY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) - -#define SDL_RETURN_CAPABILITY(x) \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) - -#define SDL_NO_THREAD_SAFETY_ANALYSIS \ - SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) - -/******************************************************************************/ - - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Synchronization functions which can time out return this value if they time - * out. - */ -#define SDL_MUTEX_TIMEDOUT 1 - -/** - * This is the timeout value which corresponds to never time out. - */ -#define SDL_MUTEX_MAXWAIT (~(Uint32)0) - - -/** - * \name Mutex functions - */ -/* @{ */ - -/* The SDL mutex structure, defined in SDL_sysmutex.c */ -struct SDL_mutex; -typedef struct SDL_mutex SDL_mutex; - -/** - * Create a new mutex. - * - * All newly-created mutexes begin in the _unlocked_ state. - * - * Calls to SDL_LockMutex() will not return while the mutex is locked by - * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. - * - * SDL mutexes are reentrant. - * - * \returns the initialized and unlocked mutex or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroyMutex - * \sa SDL_LockMutex - * \sa SDL_TryLockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); - -/** - * Lock the mutex. - * - * This will block until the mutex is available, which is to say it is in the - * unlocked state and the OS has chosen the caller as the next thread to lock - * it. Of all threads waiting to lock the mutex, only one may do so at a time. - * - * It is legal for the owning thread to lock an already-locked mutex. It must - * unlock it the same number of times before it is actually made available for - * other threads in the system (this is known as a "recursive mutex"). - * - * \param mutex the mutex to lock. - * \return 0, or -1 on error. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex); -#define SDL_mutexP(m) SDL_LockMutex(m) - -/** - * Try to lock a mutex without blocking. - * - * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns `SDL_MUTEX_TIMEOUT` immediately. - * - * This technique is useful if you need exclusive access to a resource but - * don't want to wait for it, and will return to it to try again later. - * - * \param mutex the mutex to try to lock. - * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateMutex - * \sa SDL_DestroyMutex - * \sa SDL_LockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex) SDL_TRY_ACQUIRE(0, mutex); - -/** - * Unlock the mutex. - * - * It is legal for the owning thread to lock an already-locked mutex. It must - * unlock it the same number of times before it is actually made available for - * other threads in the system (this is known as a "recursive mutex"). - * - * It is an error to unlock a mutex that has not been locked by the current - * thread, and doing so results in undefined behavior. - * - * It is also an error to unlock a mutex that isn't locked at all. - * - * \param mutex the mutex to unlock. - * \returns 0, or -1 on error. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex); -#define SDL_mutexV(m) SDL_UnlockMutex(m) - -/** - * Destroy a mutex created with SDL_CreateMutex(). - * - * This function must be called on any mutex that is no longer needed. Failure - * to destroy a mutex will result in a system memory or resource leak. While - * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt - * to destroy a locked mutex, and may result in undefined behavior depending - * on the platform. - * - * \param mutex the mutex to destroy. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateMutex - * \sa SDL_LockMutex - * \sa SDL_TryLockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); - -/* @} *//* Mutex functions */ - - -/** - * \name Semaphore functions - */ -/* @{ */ - -/* The SDL semaphore structure, defined in SDL_syssem.c */ -struct SDL_semaphore; -typedef struct SDL_semaphore SDL_sem; - -/** - * Create a semaphore. - * - * This function creates a new semaphore and initializes it with the value - * `initial_value`. Each wait operation on the semaphore will atomically - * decrement the semaphore value and potentially block if the semaphore value - * is 0. Each post operation will atomically increment the semaphore value and - * wake waiting threads and allow them to retry the wait operation. - * - * \param initial_value the starting value of the semaphore. - * \returns a new semaphore or NULL on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); - -/** - * Destroy a semaphore. - * - * It is not safe to destroy a semaphore if there are threads currently - * waiting on it. - * - * \param sem the semaphore to destroy. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); - -/** - * Wait until a semaphore has a positive value and then decrements it. - * - * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value or the call is interrupted by a - * signal or error. If the call is successful it will atomically decrement the - * semaphore value. - * - * This function is the equivalent of calling SDL_SemWaitTimeout() with a time - * length of `SDL_MUTEX_MAXWAIT`. - * - * \param sem the semaphore wait on. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); - -/** - * See if a semaphore has a positive value and decrement it if it does. - * - * This function checks to see if the semaphore pointed to by `sem` has a - * positive value and atomically decrements the semaphore value if it does. If - * the semaphore doesn't have a positive value, the function immediately - * returns SDL_MUTEX_TIMEDOUT. - * - * \param sem the semaphore to wait on. - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would - * block, or a negative error code on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); - -/** - * Wait until a semaphore has a positive value and then decrements it. - * - * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value, the call is interrupted by a - * signal or error, or the specified time has elapsed. If the call is - * successful it will atomically decrement the semaphore value. - * - * \param sem the semaphore to wait on. - * \param timeout the length of the timeout, in milliseconds. - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not - * succeed in the allotted time, or a negative error code on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - */ -extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout); - -/** - * Atomically increment a semaphore's value and wake waiting threads. - * - * \param sem the semaphore to increment. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); - -/** - * Get the current value of a semaphore. - * - * \param sem the semaphore to query. - * \returns the current value of the semaphore. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - */ -extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); - -/* @} *//* Semaphore functions */ - - -/** - * \name Condition variable functions - */ -/* @{ */ - -/* The SDL condition variable structure, defined in SDL_syscond.c */ -struct SDL_cond; -typedef struct SDL_cond SDL_cond; - -/** - * Create a condition variable. - * - * \returns a new condition variable or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_DestroyCond - */ -extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); - -/** - * Destroy a condition variable. - * - * \param cond the condition variable to destroy. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - */ -extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); - -/** - * Restart one of the threads that are waiting on the condition variable. - * - * \param cond the condition variable to signal. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); - -/** - * Restart all threads that are waiting on the condition variable. - * - * \param cond the condition variable to signal. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); - -/** - * Wait until a condition variable is signaled. - * - * This function unlocks the specified `mutex` and waits for another thread to - * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable - * `cond`. Once the condition variable is signaled, the mutex is re-locked and - * the function returns. - * - * The mutex must be locked before calling this function. - * - * This function is the equivalent of calling SDL_CondWaitTimeout() with a - * time length of `SDL_MUTEX_MAXWAIT`. - * - * \param cond the condition variable to wait on. - * \param mutex the mutex used to coordinate thread access. - * \returns 0 when it is signaled or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); - -/** - * Wait until a condition variable is signaled or a certain time has passed. - * - * This function unlocks the specified `mutex` and waits for another thread to - * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable - * `cond`, or for the specified time to elapse. Once the condition variable is - * signaled or the time elapsed, the mutex is re-locked and the function - * returns. - * - * The mutex must be locked before calling this function. - * - * \param cond the condition variable to wait on. - * \param mutex the mutex used to coordinate thread access. - * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT` - * to wait indefinitely. - * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if - * the condition is not signaled in the allotted time, or a negative - * error code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, - SDL_mutex * mutex, Uint32 ms); - -/* @} *//* Condition variable functions */ - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_mutex_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_name.h b/code/thirdparty/SDL2-2.32.8/include/SDL_name.h deleted file mode 100644 index 0c48bcf315..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_name.h +++ /dev/null @@ -1,33 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDLname_h_ -#define SDLname_h_ - -#if defined(__STDC__) || defined(__cplusplus) -#define NeedFunctionPrototypes 1 -#endif - -#define SDL_NAME(X) SDL_##X - -#endif /* SDLname_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_pixels.h b/code/thirdparty/SDL2-2.32.8/include/SDL_pixels.h deleted file mode 100644 index 6f29811d33..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_pixels.h +++ /dev/null @@ -1,686 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryPixels - * - * Header for the enumerated pixel format definitions. - */ - -#ifndef SDL_pixels_h_ -#define SDL_pixels_h_ - -#include "SDL_stdinc.h" -#include "SDL_endian.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \name Transparency definitions - * - * These define alpha as the opacity of a surface. - */ -/* @{ */ -#define SDL_ALPHA_OPAQUE 255 -#define SDL_ALPHA_TRANSPARENT 0 -/* @} */ - -/** Pixel type. */ -typedef enum -{ - SDL_PIXELTYPE_UNKNOWN, - SDL_PIXELTYPE_INDEX1, - SDL_PIXELTYPE_INDEX4, - SDL_PIXELTYPE_INDEX8, - SDL_PIXELTYPE_PACKED8, - SDL_PIXELTYPE_PACKED16, - SDL_PIXELTYPE_PACKED32, - SDL_PIXELTYPE_ARRAYU8, - SDL_PIXELTYPE_ARRAYU16, - SDL_PIXELTYPE_ARRAYU32, - SDL_PIXELTYPE_ARRAYF16, - SDL_PIXELTYPE_ARRAYF32, - - /* This must be at the end of the list to avoid breaking the existing ABI */ - SDL_PIXELTYPE_INDEX2 -} SDL_PixelType; - -/** Bitmap pixel order, high bit -> low bit. */ -typedef enum -{ - SDL_BITMAPORDER_NONE, - SDL_BITMAPORDER_4321, - SDL_BITMAPORDER_1234 -} SDL_BitmapOrder; - -/** Packed component order, high bit -> low bit. */ -typedef enum -{ - SDL_PACKEDORDER_NONE, - SDL_PACKEDORDER_XRGB, - SDL_PACKEDORDER_RGBX, - SDL_PACKEDORDER_ARGB, - SDL_PACKEDORDER_RGBA, - SDL_PACKEDORDER_XBGR, - SDL_PACKEDORDER_BGRX, - SDL_PACKEDORDER_ABGR, - SDL_PACKEDORDER_BGRA -} SDL_PackedOrder; - -/** Array component order, low byte -> high byte. */ -/* !!! FIXME: in 2.1, make these not overlap differently with - !!! FIXME: SDL_PACKEDORDER_*, so we can simplify SDL_ISPIXELFORMAT_ALPHA */ -typedef enum -{ - SDL_ARRAYORDER_NONE, - SDL_ARRAYORDER_RGB, - SDL_ARRAYORDER_RGBA, - SDL_ARRAYORDER_ARGB, - SDL_ARRAYORDER_BGR, - SDL_ARRAYORDER_BGRA, - SDL_ARRAYORDER_ABGR -} SDL_ArrayOrder; - -/** Packed component layout. */ -typedef enum -{ - SDL_PACKEDLAYOUT_NONE, - SDL_PACKEDLAYOUT_332, - SDL_PACKEDLAYOUT_4444, - SDL_PACKEDLAYOUT_1555, - SDL_PACKEDLAYOUT_5551, - SDL_PACKEDLAYOUT_565, - SDL_PACKEDLAYOUT_8888, - SDL_PACKEDLAYOUT_2101010, - SDL_PACKEDLAYOUT_1010102 -} SDL_PackedLayout; - -#define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) - -#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) (((X) >> 8) & 0xFF) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU)) ? 2 : 1) : (((X) >> 0) & 0xFF)) - -#define SDL_ISPIXELFORMAT_INDEXED(format) \ - (!SDL_ISPIXELFORMAT_FOURCC(format) && \ - ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) - -#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))) - -#define SDL_ISPIXELFORMAT_ARRAY(format) \ - (!SDL_ISPIXELFORMAT_FOURCC(format) && \ - ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ - (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) - -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ - (SDL_ISPIXELFORMAT_ARRAY(format) && \ - ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ - (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) \ - ((format) && (SDL_PIXELFLAG(format) != 1)) - -/* Note: If you modify this list, update SDL_GetPixelFormatName() */ -typedef enum -{ - SDL_PIXELFORMAT_UNKNOWN, - SDL_PIXELFORMAT_INDEX1LSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, - 1, 0), - SDL_PIXELFORMAT_INDEX1MSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, - 1, 0), - SDL_PIXELFORMAT_INDEX2LSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, - 2, 0), - SDL_PIXELFORMAT_INDEX2MSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, - 2, 0), - SDL_PIXELFORMAT_INDEX4LSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, - 4, 0), - SDL_PIXELFORMAT_INDEX4MSB = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, - 4, 0), - SDL_PIXELFORMAT_INDEX8 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), - SDL_PIXELFORMAT_RGB332 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, - SDL_PACKEDLAYOUT_332, 8, 1), - SDL_PIXELFORMAT_XRGB4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, - SDL_PACKEDLAYOUT_4444, 12, 2), - SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444, - SDL_PIXELFORMAT_XBGR4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, - SDL_PACKEDLAYOUT_4444, 12, 2), - SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444, - SDL_PIXELFORMAT_XRGB1555 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, - SDL_PACKEDLAYOUT_1555, 15, 2), - SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555, - SDL_PIXELFORMAT_XBGR1555 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, - SDL_PACKEDLAYOUT_1555, 15, 2), - SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555, - SDL_PIXELFORMAT_ARGB4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, - SDL_PACKEDLAYOUT_4444, 16, 2), - SDL_PIXELFORMAT_RGBA4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, - SDL_PACKEDLAYOUT_4444, 16, 2), - SDL_PIXELFORMAT_ABGR4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, - SDL_PACKEDLAYOUT_4444, 16, 2), - SDL_PIXELFORMAT_BGRA4444 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, - SDL_PACKEDLAYOUT_4444, 16, 2), - SDL_PIXELFORMAT_ARGB1555 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, - SDL_PACKEDLAYOUT_1555, 16, 2), - SDL_PIXELFORMAT_RGBA5551 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, - SDL_PACKEDLAYOUT_5551, 16, 2), - SDL_PIXELFORMAT_ABGR1555 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, - SDL_PACKEDLAYOUT_1555, 16, 2), - SDL_PIXELFORMAT_BGRA5551 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, - SDL_PACKEDLAYOUT_5551, 16, 2), - SDL_PIXELFORMAT_RGB565 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, - SDL_PACKEDLAYOUT_565, 16, 2), - SDL_PIXELFORMAT_BGR565 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, - SDL_PACKEDLAYOUT_565, 16, 2), - SDL_PIXELFORMAT_RGB24 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, - 24, 3), - SDL_PIXELFORMAT_BGR24 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, - 24, 3), - SDL_PIXELFORMAT_XRGB8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, - SDL_PACKEDLAYOUT_8888, 24, 4), - SDL_PIXELFORMAT_RGB888 = SDL_PIXELFORMAT_XRGB8888, - SDL_PIXELFORMAT_RGBX8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, - SDL_PACKEDLAYOUT_8888, 24, 4), - SDL_PIXELFORMAT_XBGR8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, - SDL_PACKEDLAYOUT_8888, 24, 4), - SDL_PIXELFORMAT_BGR888 = SDL_PIXELFORMAT_XBGR8888, - SDL_PIXELFORMAT_BGRX8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, - SDL_PACKEDLAYOUT_8888, 24, 4), - SDL_PIXELFORMAT_ARGB8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, - SDL_PACKEDLAYOUT_8888, 32, 4), - SDL_PIXELFORMAT_RGBA8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, - SDL_PACKEDLAYOUT_8888, 32, 4), - SDL_PIXELFORMAT_ABGR8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, - SDL_PACKEDLAYOUT_8888, 32, 4), - SDL_PIXELFORMAT_BGRA8888 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, - SDL_PACKEDLAYOUT_8888, 32, 4), - SDL_PIXELFORMAT_ARGB2101010 = - SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, - SDL_PACKEDLAYOUT_2101010, 32, 4), - - /* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN - SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, - SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, - SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, - SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, - SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, - SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, - SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, - SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888, -#else - SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, - SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, - SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, - SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, - SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, - SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, - SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, - SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888, -#endif - - SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */ - SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), - SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */ - SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), - SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ - SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), - SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ - SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), - SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ - SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), - SDL_PIXELFORMAT_NV12 = /**< Planar mode: Y + U/V interleaved (2 planes) */ - SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), - SDL_PIXELFORMAT_NV21 = /**< Planar mode: Y + V/U interleaved (2 planes) */ - SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), - SDL_PIXELFORMAT_EXTERNAL_OES = /**< Android video texture format */ - SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') -} SDL_PixelFormatEnum; - -/** - * The bits of this structure can be directly reinterpreted as an - * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format - * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and - * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). - */ -typedef struct SDL_Color -{ - Uint8 r; - Uint8 g; - Uint8 b; - Uint8 a; -} SDL_Color; -#define SDL_Colour SDL_Color - -typedef struct SDL_Palette -{ - int ncolors; - SDL_Color *colors; - Uint32 version; - int refcount; -} SDL_Palette; - -/** - * A structure that contains pixel format information. - * - * Everything in the pixel format structure is read-only. - * - * A pixel format has either a palette or masks. If a palette is used `Rmask`, - * `Gmask`, `Bmask`, and `Amask` will be 0. - * - * An SDL_PixelFormat describes the format of the pixel data stored at the - * `pixels` field of an SDL_Surface. Every surface stores an SDL_PixelFormat - * in the `format` field. - * - * If you wish to do pixel level modifications on a surface, then - * understanding how SDL stores its color information is essential. - * - * For information on modern pixel color spaces, see the following Wikipedia - * article: http://en.wikipedia.org/wiki/RGBA_color_space - * - * \sa SDL_ConvertSurface - * \sa SDL_GetRGB - * \sa SDL_GetRGBA - * \sa SDL_MapRGB - * \sa SDL_MapRGBA - * \sa SDL_AllocFormat - * \sa SDL_FreeFormat - */ -typedef struct SDL_PixelFormat -{ - Uint32 format; - SDL_Palette *palette; - Uint8 BitsPerPixel; - Uint8 BytesPerPixel; - Uint8 padding[2]; - Uint32 Rmask; - Uint32 Gmask; - Uint32 Bmask; - Uint32 Amask; - Uint8 Rloss; - Uint8 Gloss; - Uint8 Bloss; - Uint8 Aloss; - Uint8 Rshift; - Uint8 Gshift; - Uint8 Bshift; - Uint8 Ashift; - int refcount; - struct SDL_PixelFormat *next; -} SDL_PixelFormat; - -/** - * Get the human readable name of a pixel format. - * - * \param format the pixel format to query. - * \returns the human readable name of the specified pixel format or - * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); - -/** - * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. - * - * \param format one of the SDL_PixelFormatEnum values. - * \param bpp a bits per pixel value; usually 15, 16, or 32. - * \param Rmask a pointer filled in with the red mask for the format. - * \param Gmask a pointer filled in with the green mask for the format. - * \param Bmask a pointer filled in with the blue mask for the format. - * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't - * possible; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MasksToPixelFormatEnum - */ -extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, - int *bpp, - Uint32 * Rmask, - Uint32 * Gmask, - Uint32 * Bmask, - Uint32 * Amask); - -/** - * Convert a bpp value and RGBA masks to an enumerated pixel format. - * - * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't - * possible. - * - * \param bpp a bits per pixel value; usually 15, 16, or 32. - * \param Rmask the red mask for the format. - * \param Gmask the green mask for the format. - * \param Bmask the blue mask for the format. - * \param Amask the alpha mask for the format. - * \returns one of the SDL_PixelFormatEnum values. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_PixelFormatEnumToMasks - */ -extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, - Uint32 Rmask, - Uint32 Gmask, - Uint32 Bmask, - Uint32 Amask); - -/** - * Create an SDL_PixelFormat structure corresponding to a pixel format. - * - * Returned structure may come from a shared global cache (i.e. not newly - * allocated), and hence should not be modified, especially the palette. Weird - * errors such as `Blit combination not supported` may occur. - * - * \param pixel_format one of the SDL_PixelFormatEnum values. - * \returns the new SDL_PixelFormat structure or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeFormat - */ -extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); - -/** - * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). - * - * \param format the SDL_PixelFormat structure to free. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocFormat - */ -extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format); - -/** - * Create a palette structure with the specified number of color entries. - * - * The palette entries are initialized to white. - * - * \param ncolors represents the number of color entries in the color palette. - * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if - * there wasn't enough memory); call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreePalette - */ -extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); - -/** - * Set the palette for a pixel format structure. - * - * \param format the SDL_PixelFormat structure that will use the palette. - * \param palette the SDL_Palette structure that will be used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocPalette - * \sa SDL_FreePalette - */ -extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, - SDL_Palette *palette); - -/** - * Set a range of colors in a palette. - * - * \param palette the SDL_Palette structure to modify. - * \param colors an array of SDL_Color structures to copy into the palette. - * \param firstcolor the index of the first palette entry to modify. - * \param ncolors the number of entries to modify. - * \returns 0 on success or a negative error code if not all of the colors - * could be set; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocPalette - * \sa SDL_CreateRGBSurface - */ -extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, - const SDL_Color * colors, - int firstcolor, int ncolors); - -/** - * Free a palette created with SDL_AllocPalette(). - * - * \param palette the SDL_Palette structure to be freed. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocPalette - */ -extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); - -/** - * Map an RGB triple to an opaque pixel value for a given pixel format. - * - * This function maps the RGB color value to the specified pixel format and - * returns the pixel value best approximating the given RGB color value for - * the given pixel format. - * - * If the format has a palette (8-bit) the index of the closest matching color - * in the palette will be returned. - * - * If the specified pixel format has an alpha component it will be returned as - * all 1 bits (fully opaque). - * - * If the pixel format bpp (color depth) is less than 32-bpp then the unused - * upper bits of the return value can safely be ignored (e.g., with a 16-bpp - * format the return value can be assigned to a Uint16, and similarly a Uint8 - * for an 8-bpp format). - * - * \param format an SDL_PixelFormat structure describing the pixel format. - * \param r the red component of the pixel in the range 0-255. - * \param g the green component of the pixel in the range 0-255. - * \param b the blue component of the pixel in the range 0-255. - * \returns a pixel value. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRGB - * \sa SDL_GetRGBA - * \sa SDL_MapRGBA - */ -extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, - Uint8 r, Uint8 g, Uint8 b); - -/** - * Map an RGBA quadruple to a pixel value for a given pixel format. - * - * This function maps the RGBA color value to the specified pixel format and - * returns the pixel value best approximating the given RGBA color value for - * the given pixel format. - * - * If the specified pixel format has no alpha component the alpha value will - * be ignored (as it will be in formats with a palette). - * - * If the format has a palette (8-bit) the index of the closest matching color - * in the palette will be returned. - * - * If the pixel format bpp (color depth) is less than 32-bpp then the unused - * upper bits of the return value can safely be ignored (e.g., with a 16-bpp - * format the return value can be assigned to a Uint16, and similarly a Uint8 - * for an 8-bpp format). - * - * \param format an SDL_PixelFormat structure describing the format of the - * pixel. - * \param r the red component of the pixel in the range 0-255. - * \param g the green component of the pixel in the range 0-255. - * \param b the blue component of the pixel in the range 0-255. - * \param a the alpha component of the pixel in the range 0-255. - * \returns a pixel value. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRGB - * \sa SDL_GetRGBA - * \sa SDL_MapRGB - */ -extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, - Uint8 r, Uint8 g, Uint8 b, - Uint8 a); - -/** - * Get RGB values from a pixel in the specified format. - * - * This function uses the entire 8-bit [0..255] range when converting color - * components from pixel formats with less than 8-bits per RGB component - * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, - * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). - * - * \param pixel a pixel value. - * \param format an SDL_PixelFormat structure describing the format of the - * pixel. - * \param r a pointer filled in with the red component. - * \param g a pointer filled in with the green component. - * \param b a pointer filled in with the blue component. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRGBA - * \sa SDL_MapRGB - * \sa SDL_MapRGBA - */ -extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, - const SDL_PixelFormat * format, - Uint8 * r, Uint8 * g, Uint8 * b); - -/** - * Get RGBA values from a pixel in the specified format. - * - * This function uses the entire 8-bit [0..255] range when converting color - * components from pixel formats with less than 8-bits per RGB component - * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, - * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). - * - * If the surface has no alpha component, the alpha will be returned as 0xff - * (100% opaque). - * - * \param pixel a pixel value. - * \param format an SDL_PixelFormat structure describing the format of the - * pixel. - * \param r a pointer filled in with the red component. - * \param g a pointer filled in with the green component. - * \param b a pointer filled in with the blue component. - * \param a a pointer filled in with the alpha component. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRGB - * \sa SDL_MapRGB - * \sa SDL_MapRGBA - */ -extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, - const SDL_PixelFormat * format, - Uint8 * r, Uint8 * g, Uint8 * b, - Uint8 * a); - -/** - * Calculate a 256 entry gamma ramp for a gamma value. - * - * \param gamma a gamma value where 0.0 is black and 1.0 is identity. - * \param ramp an array of 256 values filled in with the gamma ramp. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowGammaRamp - */ -extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_pixels_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_platform.h b/code/thirdparty/SDL2-2.32.8/include/SDL_platform.h deleted file mode 100644 index 64ece4fe70..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_platform.h +++ /dev/null @@ -1,275 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryPlatform - * - * Try to get a standard set of platform defines. - */ - -#ifndef SDL_platform_h_ -#define SDL_platform_h_ - -#if defined(_AIX) -#undef __AIX__ -#define __AIX__ 1 -#endif -#if defined(__HAIKU__) -#undef __HAIKU__ -#define __HAIKU__ 1 -#endif -#if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#undef __BSDI__ -#define __BSDI__ 1 -#endif -#if defined(_arch_dreamcast) -#undef __DREAMCAST__ -#define __DREAMCAST__ 1 -#endif -#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) -#undef __FREEBSD__ -#define __FREEBSD__ 1 -#endif -#if defined(hpux) || defined(__hpux) || defined(__hpux__) -#undef __HPUX__ -#define __HPUX__ 1 -#endif -#if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#undef __IRIX__ -#define __IRIX__ 1 -#endif -#if (defined(linux) || defined(__linux) || defined(__linux__)) -#undef __LINUX__ -#define __LINUX__ 1 -#endif -#if defined(ANDROID) || defined(__ANDROID__) -#undef __ANDROID__ -#undef __LINUX__ /* do we need to do this? */ -#define __ANDROID__ 1 -#endif -#if defined(__NGAGE__) -#undef __NGAGE__ -#define __NGAGE__ 1 -#endif - -#if defined(__APPLE__) -/* lets us know what version of Mac OS X we're compiling on */ -#include -#ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension -#else -#include -#endif - -/* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets -*/ -#ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 -#endif -#ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 -#endif -#ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 -#endif -#ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 -#endif -#ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 -#endif - -#if TARGET_OS_TV -#undef __TVOS__ -#define __TVOS__ 1 -#endif -#if TARGET_OS_IPHONE -/* if compiling for iOS */ -#undef __IPHONEOS__ -#define __IPHONEOS__ 1 -#undef __MACOSX__ -#else -/* if not compiling for iOS */ -#undef __MACOSX__ -#define __MACOSX__ 1 -#if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for Mac OS X only supports deploying on 10.7 and above. -#endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ -#endif /* TARGET_OS_IPHONE */ -#endif /* defined(__APPLE__) */ - -#if defined(__NetBSD__) -#undef __NETBSD__ -#define __NETBSD__ 1 -#endif -#if defined(__OpenBSD__) -#undef __OPENBSD__ -#define __OPENBSD__ 1 -#endif -#if defined(__OS2__) || defined(__EMX__) -#undef __OS2__ -#define __OS2__ 1 -#endif -#if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#undef __OSF__ -#define __OSF__ 1 -#endif -#if defined(__QNXNTO__) -#undef __QNXNTO__ -#define __QNXNTO__ 1 -#endif -#if defined(riscos) || defined(__riscos) || defined(__riscos__) -#undef __RISCOS__ -#define __RISCOS__ 1 -#endif -#if defined(__sun) && defined(__SVR4) -#undef __SOLARIS__ -#define __SOLARIS__ 1 -#endif - -#if defined(WIN32) || defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) -/* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ -#if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif - -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ -#elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif - -#if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) -#else -#define WINAPI_FAMILY_WINRT 0 -#endif /* HAVE_WINAPIFAMILY_H */ - -#if (HAVE_WINAPIFAMILY_H) && defined(WINAPI_FAMILY_PHONE_APP) -#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) -#else -#define SDL_WINAPI_FAMILY_PHONE 0 -#endif - -#if WINAPI_FAMILY_WINRT -#undef __WINRT__ -#define __WINRT__ 1 -#elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ -#undef __WINGDK__ -#define __WINGDK__ 1 -#elif defined(_GAMING_XBOX_XBOXONE) -#undef __XBOXONE__ -#define __XBOXONE__ 1 -#elif defined(_GAMING_XBOX_SCARLETT) -#undef __XBOXSERIES__ -#define __XBOXSERIES__ 1 -#else -#undef __WINDOWS__ -#define __WINDOWS__ 1 -#endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(__CYGWIN__) */ - -#if defined(__WINDOWS__) -#undef __WIN32__ -#define __WIN32__ 1 -#endif -/* This is to support generic "any GDK" separate from a platform-specific GDK */ -#if defined(__WINGDK__) || defined(__XBOXONE__) || defined(__XBOXSERIES__) -#undef __GDK__ -#define __GDK__ 1 -#endif -#if defined(__PSP__) || defined(__psp__) -#ifdef __PSP__ -#undef __PSP__ -#endif -#define __PSP__ 1 -#endif -#if defined(PS2) -#define __PS2__ 1 -#endif - -/* The NACL compiler defines __native_client__ and __pnacl__ - * Ref: http://www.chromium.org/nativeclient/pnacl/stability-of-the-pnacl-bitcode-abi - */ -#if defined(__native_client__) -#undef __LINUX__ -#undef __NACL__ -#define __NACL__ 1 -#endif -#if defined(__pnacl__) -#undef __LINUX__ -#undef __PNACL__ -#define __PNACL__ 1 -/* PNACL with newlib supports static linking only */ -#define __SDL_NOGETPROCADDR__ -#endif - -#if defined(__vita__) -#define __VITA__ 1 -#endif - -#if defined(__3DS__) -#undef __3DS__ -#define __3DS__ 1 -#endif - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Get the name of the platform. - * - * Here are the names returned for some (but not all) supported platforms: - * - * - "Windows" - * - "Mac OS X" - * - "Linux" - * - "iOS" - * - "Android" - * - * \returns the name of the platform. If the correct platform name is not - * available, returns a string beginning with the text "Unknown". - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_platform_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_quit.h b/code/thirdparty/SDL2-2.32.8/include/SDL_quit.h deleted file mode 100644 index 03630e232b..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_quit.h +++ /dev/null @@ -1,50 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryQuit - * - * An SDL_QUIT event is generated when the user tries to close the application - * window. If it is ignored or filtered out, the window will remain open. If - * it is not ignored or filtered, it is queued normally and the window is - * allowed to close. When the window is closed, screen updates will complete, - * but have no effect. - * - * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) and - * SIGTERM (system termination request), if handlers do not already exist, - * that generate SDL_QUIT events as well. There is no way to determine the - * cause of an SDL_QUIT event, but setting a signal handler in your - * application will override the default generation of quit events for that - * signal. - */ - -#ifndef SDL_quit_h_ -#define SDL_quit_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -/* There are no functions directly affecting the quit event */ - -#define SDL_QuitRequested() \ - (SDL_PumpEvents(), (SDL_PeepEvents(NULL,0,SDL_PEEKEVENT,SDL_QUIT,SDL_QUIT) > 0)) - -#endif /* SDL_quit_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_rect.h b/code/thirdparty/SDL2-2.32.8/include/SDL_rect.h deleted file mode 100644 index b7e609d941..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_rect.h +++ /dev/null @@ -1,376 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryRect - * - * Header file for SDL_rect definition and management functions. - */ - -#ifndef SDL_rect_h_ -#define SDL_rect_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_pixels.h" -#include "SDL_rwops.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * The structure that defines a point (integer) - * - * \sa SDL_EnclosePoints - * \sa SDL_PointInRect - */ -typedef struct SDL_Point -{ - int x; - int y; -} SDL_Point; - -/** - * The structure that defines a point (floating point) - * - * \sa SDL_EncloseFPoints - * \sa SDL_PointInFRect - */ -typedef struct SDL_FPoint -{ - float x; - float y; -} SDL_FPoint; - - -/** - * A rectangle, with the origin at the upper left (integer). - * - * \sa SDL_RectEmpty - * \sa SDL_RectEquals - * \sa SDL_HasIntersection - * \sa SDL_IntersectRect - * \sa SDL_IntersectRectAndLine - * \sa SDL_UnionRect - * \sa SDL_EnclosePoints - */ -typedef struct SDL_Rect -{ - int x, y; - int w, h; -} SDL_Rect; - - -/** - * A rectangle, with the origin at the upper left (floating point). - * - * \sa SDL_FRectEmpty - * \sa SDL_FRectEquals - * \sa SDL_FRectEqualsEpsilon - * \sa SDL_HasIntersectionF - * \sa SDL_IntersectFRect - * \sa SDL_IntersectFRectAndLine - * \sa SDL_UnionFRect - * \sa SDL_EncloseFPoints - * \sa SDL_PointInFRect - */ -typedef struct SDL_FRect -{ - float x; - float y; - float w; - float h; -} SDL_FRect; - - -/** - * Returns true if point resides inside a rectangle. - */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) -{ - return ( (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; -} - -/** - * Returns true if the rectangle has no area. - */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) -{ - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; -} - -/** - * Returns true if the two rectangles are equal. - */ -SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b) -{ - return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; -} - -/** - * Determine whether two rectangles intersect. - * - * If either pointer is NULL the function will return SDL_FALSE. - * - * \param A an SDL_Rect structure representing the first rectangle. - * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_IntersectRect - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A, - const SDL_Rect * B); - -/** - * Calculate the intersection of two rectangles. - * - * If `result` is NULL then this function will return SDL_FALSE. - * - * \param A an SDL_Rect structure representing the first rectangle. - * \param B an SDL_Rect structure representing the second rectangle. - * \param result an SDL_Rect structure filled in with the intersection of - * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HasIntersection - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A, - const SDL_Rect * B, - SDL_Rect * result); - -/** - * Calculate the union of two rectangles. - * - * \param A an SDL_Rect structure representing the first rectangle. - * \param B an SDL_Rect structure representing the second rectangle. - * \param result an SDL_Rect structure filled in with the union of rectangles - * `A` and `B`. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A, - const SDL_Rect * B, - SDL_Rect * result); - -/** - * Calculate a minimal rectangle enclosing a set of points. - * - * If `clip` is not NULL then only points inside of the clipping rectangle are - * considered. - * - * \param points an array of SDL_Point structures representing points to be - * enclosed. - * \param count the number of structures in the `points` array. - * \param clip an SDL_Rect used for clipping or NULL to enclose all points. - * \param result an SDL_Rect structure filled in with the minimal enclosing - * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points, - int count, - const SDL_Rect * clip, - SDL_Rect * result); - -/** - * Calculate the intersection of a rectangle and line segment. - * - * This function is used to clip a line segment to a rectangle. A line segment - * contained entirely within the rectangle or that does not intersect will - * remain unchanged. A line segment that crosses the rectangle at either or - * both ends will be clipped to the boundary of the rectangle and the new - * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. - * - * \param rect an SDL_Rect structure representing the rectangle to intersect. - * \param X1 a pointer to the starting X-coordinate of the line. - * \param Y1 a pointer to the starting Y-coordinate of the line. - * \param X2 a pointer to the ending X-coordinate of the line. - * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect * - rect, int *X1, - int *Y1, int *X2, - int *Y2); - - -/* SDL_FRect versions... */ - -/** - * Returns true if point resides inside a rectangle. - */ -SDL_FORCE_INLINE SDL_bool SDL_PointInFRect(const SDL_FPoint *p, const SDL_FRect *r) -{ - return ( (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; -} - -/** - * Returns true if the rectangle has no area. - */ -SDL_FORCE_INLINE SDL_bool SDL_FRectEmpty(const SDL_FRect *r) -{ - return ((!r) || (r->w <= 0.0f) || (r->h <= 0.0f)) ? SDL_TRUE : SDL_FALSE; -} - -/** - * Returns true if the two rectangles are equal, within some given epsilon. - * - * \since This function is available since SDL 2.0.22. - */ -SDL_FORCE_INLINE SDL_bool SDL_FRectEqualsEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) -{ - return (a && b && ((a == b) || - ((SDL_fabsf(a->x - b->x) <= epsilon) && - (SDL_fabsf(a->y - b->y) <= epsilon) && - (SDL_fabsf(a->w - b->w) <= epsilon) && - (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; -} - -/** - * Returns true if the two rectangles are equal, using a default epsilon. - * - * \since This function is available since SDL 2.0.22. - */ -SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b) -{ - return SDL_FRectEqualsEpsilon(a, b, SDL_FLT_EPSILON); -} - -/** - * Determine whether two rectangles intersect with float precision. - * - * If either pointer is NULL the function will return SDL_FALSE. - * - * \param A an SDL_FRect structure representing the first rectangle. - * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.22. - * - * \sa SDL_IntersectRect - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersectionF(const SDL_FRect * A, - const SDL_FRect * B); - -/** - * Calculate the intersection of two rectangles with float precision. - * - * If `result` is NULL then this function will return SDL_FALSE. - * - * \param A an SDL_FRect structure representing the first rectangle. - * \param B an SDL_FRect structure representing the second rectangle. - * \param result an SDL_FRect structure filled in with the intersection of - * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.22. - * - * \sa SDL_HasIntersectionF - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRect(const SDL_FRect * A, - const SDL_FRect * B, - SDL_FRect * result); - -/** - * Calculate the union of two rectangles with float precision. - * - * \param A an SDL_FRect structure representing the first rectangle. - * \param B an SDL_FRect structure representing the second rectangle. - * \param result an SDL_FRect structure filled in with the union of rectangles - * `A` and `B`. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC void SDLCALL SDL_UnionFRect(const SDL_FRect * A, - const SDL_FRect * B, - SDL_FRect * result); - -/** - * Calculate a minimal rectangle enclosing a set of points with float - * precision. - * - * If `clip` is not NULL then only points inside of the clipping rectangle are - * considered. - * - * \param points an array of SDL_FPoint structures representing points to be - * enclosed. - * \param count the number of structures in the `points` array. - * \param clip an SDL_FRect used for clipping or NULL to enclose all points. - * \param result an SDL_FRect structure filled in with the minimal enclosing - * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_EncloseFPoints(const SDL_FPoint * points, - int count, - const SDL_FRect * clip, - SDL_FRect * result); - -/** - * Calculate the intersection of a rectangle and line segment with float - * precision. - * - * This function is used to clip a line segment to a rectangle. A line segment - * contained entirely within the rectangle or that does not intersect will - * remain unchanged. A line segment that crosses the rectangle at either or - * both ends will be clipped to the boundary of the rectangle and the new - * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. - * - * \param rect an SDL_FRect structure representing the rectangle to intersect. - * \param X1 a pointer to the starting X-coordinate of the line. - * \param Y1 a pointer to the starting Y-coordinate of the line. - * \param X2 a pointer to the ending X-coordinate of the line. - * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRectAndLine(const SDL_FRect * - rect, float *X1, - float *Y1, float *X2, - float *Y2); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_rect_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_render.h b/code/thirdparty/SDL2-2.32.8/include/SDL_render.h deleted file mode 100644 index 5274172179..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_render.h +++ /dev/null @@ -1,1932 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryRender - * - * Header file for SDL 2D rendering functions. - * - * This API supports the following features: - * - * - single pixel points - * - single pixel lines - * - filled rectangles - * - texture images - * - * The primitives may be drawn in opaque, blended, or additive modes. - * - * The texture images may be drawn in opaque, blended, or additive modes. They - * can have an additional color tint or alpha modulation applied to them, and - * may also be stretched with linear interpolation. - * - * This API is designed to accelerate simple 2D operations. You may want more - * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. - * - * These functions must be called from the main thread. See this bug for - * details: https://github.com/libsdl-org/SDL/issues/986 - */ - -#ifndef SDL_render_h_ -#define SDL_render_h_ - -#include "SDL_stdinc.h" -#include "SDL_rect.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Flags used when creating a rendering context - */ -typedef enum SDL_RendererFlags -{ - SDL_RENDERER_SOFTWARE = 0x00000001, /**< The renderer is a software fallback */ - SDL_RENDERER_ACCELERATED = 0x00000002, /**< The renderer uses hardware - acceleration */ - SDL_RENDERER_PRESENTVSYNC = 0x00000004, /**< Present is synchronized - with the refresh rate */ - SDL_RENDERER_TARGETTEXTURE = 0x00000008 /**< The renderer supports - rendering to texture */ -} SDL_RendererFlags; - -/** - * Information on the capabilities of a render driver or context. - */ -typedef struct SDL_RendererInfo -{ - const char *name; /**< The name of the renderer */ - Uint32 flags; /**< Supported SDL_RendererFlags */ - Uint32 num_texture_formats; /**< The number of available texture formats */ - Uint32 texture_formats[16]; /**< The available texture formats */ - int max_texture_width; /**< The maximum texture width */ - int max_texture_height; /**< The maximum texture height */ -} SDL_RendererInfo; - -/** - * Vertex structure - */ -typedef struct SDL_Vertex -{ - SDL_FPoint position; /**< Vertex position, in SDL_Renderer coordinates */ - SDL_Color color; /**< Vertex color */ - SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */ -} SDL_Vertex; - -/** - * The scaling mode for a texture. - */ -typedef enum SDL_ScaleMode -{ - SDL_ScaleModeNearest, /**< nearest pixel sampling */ - SDL_ScaleModeLinear, /**< linear filtering */ - SDL_ScaleModeBest /**< anisotropic filtering */ -} SDL_ScaleMode; - -/** - * The access pattern allowed for a texture. - */ -typedef enum SDL_TextureAccess -{ - SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */ - SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */ - SDL_TEXTUREACCESS_TARGET /**< Texture can be used as a render target */ -} SDL_TextureAccess; - -/** - * The texture channel modulation used in SDL_RenderCopy(). - */ -typedef enum SDL_TextureModulate -{ - SDL_TEXTUREMODULATE_NONE = 0x00000000, /**< No modulation */ - SDL_TEXTUREMODULATE_COLOR = 0x00000001, /**< srcC = srcC * color */ - SDL_TEXTUREMODULATE_ALPHA = 0x00000002 /**< srcA = srcA * alpha */ -} SDL_TextureModulate; - -/** - * Flip constants for SDL_RenderCopyEx - */ -typedef enum SDL_RendererFlip -{ - SDL_FLIP_NONE = 0x00000000, /**< Do not flip */ - SDL_FLIP_HORIZONTAL = 0x00000001, /**< flip horizontally */ - SDL_FLIP_VERTICAL = 0x00000002 /**< flip vertically */ -} SDL_RendererFlip; - -/** - * A structure representing rendering state - */ -struct SDL_Renderer; -typedef struct SDL_Renderer SDL_Renderer; - -/** - * An efficient driver-specific representation of pixel data - */ -struct SDL_Texture; -typedef struct SDL_Texture SDL_Texture; - -/* Function prototypes */ - -/** - * Get the number of 2D rendering drivers available for the current display. - * - * A render driver is a set of code that handles rendering and texture - * management on a particular display. Normally there is only one, but some - * drivers may have several available with different capabilities. - * - * There may be none if SDL was compiled without render support. - * - * \returns a number >= 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - * \sa SDL_GetRenderDriverInfo - */ -extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); - -/** - * Get info about a specific 2D rendering driver for the current display. - * - * \param index the index of the driver to query information about. - * \param info an SDL_RendererInfo structure to be filled with information on - * the rendering driver. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - * \sa SDL_GetNumRenderDrivers - */ -extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, - SDL_RendererInfo * info); - -/** - * Create a window and default renderer. - * - * \param width the width of the window. - * \param height the height of the window. - * \param window_flags the flags used to create the window (see - * SDL_CreateWindow()). - * \param window a pointer filled with the window, or NULL on error. - * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns 0 on success, or -1 on error; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - * \sa SDL_CreateWindow - */ -extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( - int width, int height, Uint32 window_flags, - SDL_Window **window, SDL_Renderer **renderer); - - -/** - * Create a 2D rendering context for a window. - * - * \param window the window where rendering is displayed. - * \param index the index of the rendering driver to initialize, or -1 to - * initialize the first one supporting the requested flags. - * \param flags 0, or one or more SDL_RendererFlags OR'd together. - * \returns a valid rendering context or NULL if there was an error; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSoftwareRenderer - * \sa SDL_DestroyRenderer - * \sa SDL_GetNumRenderDrivers - * \sa SDL_GetRendererInfo - */ -extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, - int index, Uint32 flags); - -/** - * Create a 2D software rendering context for a surface. - * - * Two other API which can be used to create SDL_Renderer: - * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_ - * create a software renderer, but they are intended to be used with an - * SDL_Window as the final destination and not an SDL_Surface. - * - * \param surface the SDL_Surface structure representing the surface where - * rendering is done. - * \returns a valid rendering context or NULL if there was an error; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - * \sa SDL_CreateWindowAndRenderer - * \sa SDL_DestroyRenderer - */ -extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface); - -/** - * Get the renderer associated with a window. - * - * \param window the window to query. - * \returns the rendering context on success or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - */ -extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window); - -/** - * Get the window associated with a renderer. - * - * \param renderer the renderer to query. - * \returns the window on success or NULL on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_RenderGetWindow(SDL_Renderer *renderer); - -/** - * Get information about a rendering context. - * - * \param renderer the rendering context. - * \param info an SDL_RendererInfo structure filled with information about the - * current renderer. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - */ -extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, - SDL_RendererInfo * info); - -/** - * Get the output size in pixels of a rendering context. - * - * Due to high-dpi displays, you might end up with a rendering context that - * has more pixels than the window that contains it, so use this instead of - * SDL_GetWindowSize() to decide how much drawing area you have. - * - * \param renderer the rendering context. - * \param w an int filled with the width. - * \param h an int filled with the height. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRenderer - */ -extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, - int *w, int *h); - -/** - * Create a texture for a rendering context. - * - * You can set the texture scaling method by setting - * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture. - * - * \param renderer the rendering context. - * \param format one of the enumerated values in SDL_PixelFormatEnum. - * \param access one of the enumerated values in SDL_TextureAccess. - * \param w the width of the texture in pixels. - * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateTextureFromSurface - * \sa SDL_DestroyTexture - * \sa SDL_QueryTexture - * \sa SDL_UpdateTexture - */ -extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, - Uint32 format, - int access, int w, - int h); - -/** - * Create a texture from an existing surface. - * - * The surface is not modified or freed by this function. - * - * The SDL_TextureAccess hint for the created texture is - * `SDL_TEXTUREACCESS_STATIC`. - * - * The pixel format of the created texture may be different from the pixel - * format of the surface. Use SDL_QueryTexture() to query the pixel format of - * the texture. - * - * \param renderer the rendering context. - * \param surface the SDL_Surface structure containing pixel data used to fill - * the texture. - * \returns the created texture or NULL on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateTexture - * \sa SDL_DestroyTexture - * \sa SDL_QueryTexture - */ -extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface); - -/** - * Query the attributes of a texture. - * - * \param texture the texture to query. - * \param format a pointer filled in with the raw format of the texture; the - * actual format may differ, but pixel transfers will use this - * format (one of the SDL_PixelFormatEnum values). This argument - * can be NULL if you don't need this information. - * \param access a pointer filled in with the actual access to the texture - * (one of the SDL_TextureAccess values). This argument can be - * NULL if you don't need this information. - * \param w a pointer filled in with the width of the texture in pixels. This - * argument can be NULL if you don't need this information. - * \param h a pointer filled in with the height of the texture in pixels. This - * argument can be NULL if you don't need this information. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateTexture - */ -extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, - Uint32 * format, int *access, - int *w, int *h); - -/** - * Set an additional color value multiplied into render copy operations. - * - * When this texture is rendered, during the copy operation each source color - * channel is modulated by the appropriate color value according to the - * following formula: - * - * `srcC = srcC * (color / 255)` - * - * Color modulation is not always supported by the renderer; it will return -1 - * if color modulation is not supported. - * - * \param texture the texture to update. - * \param r the red color value multiplied into copy operations. - * \param g the green color value multiplied into copy operations. - * \param b the blue color value multiplied into copy operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTextureColorMod - * \sa SDL_SetTextureAlphaMod - */ -extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture, - Uint8 r, Uint8 g, Uint8 b); - - -/** - * Get the additional color value multiplied into render copy operations. - * - * \param texture the texture to query. - * \param r a pointer filled in with the current red color value. - * \param g a pointer filled in with the current green color value. - * \param b a pointer filled in with the current blue color value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTextureAlphaMod - * \sa SDL_SetTextureColorMod - */ -extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture, - Uint8 * r, Uint8 * g, - Uint8 * b); - -/** - * Set an additional alpha value multiplied into render copy operations. - * - * When this texture is rendered, during the copy operation the source alpha - * value is modulated by this alpha value according to the following formula: - * - * `srcA = srcA * (alpha / 255)` - * - * Alpha modulation is not always supported by the renderer; it will return -1 - * if alpha modulation is not supported. - * - * \param texture the texture to update. - * \param alpha the source alpha value multiplied into copy operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTextureAlphaMod - * \sa SDL_SetTextureColorMod - */ -extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture, - Uint8 alpha); - -/** - * Get the additional alpha value multiplied into render copy operations. - * - * \param texture the texture to query. - * \param alpha a pointer filled in with the current alpha value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTextureColorMod - * \sa SDL_SetTextureAlphaMod - */ -extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture, - Uint8 * alpha); - -/** - * Set the blend mode for a texture, used by SDL_RenderCopy(). - * - * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. - * - * \param texture the texture to update. - * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTextureBlendMode - * \sa SDL_RenderCopy - */ -extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, - SDL_BlendMode blendMode); - -/** - * Get the blend mode used for texture copy operations. - * - * \param texture the texture to query. - * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetTextureBlendMode - */ -extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture, - SDL_BlendMode *blendMode); - -/** - * Set the scale mode used for texture scale operations. - * - * If the scale mode is not supported, the closest supported mode is chosen. - * - * \param texture The texture to update. - * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns 0 on success, or -1 if the texture is not valid. - * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_GetTextureScaleMode - */ -extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture, - SDL_ScaleMode scaleMode); - -/** - * Get the scale mode used for texture scale operations. - * - * \param texture the texture to query. - * \param scaleMode a pointer filled in with the current scale mode. - * \return 0 on success, or -1 if the texture is not valid. - * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_SetTextureScaleMode - */ -extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture, - SDL_ScaleMode *scaleMode); - -/** - * Associate a user-specified pointer with a texture. - * - * \param texture the texture to update. - * \param userdata the pointer to associate with the texture. - * \returns 0 on success, or -1 if the texture is not valid. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GetTextureUserData - */ -extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture * texture, - void *userdata); - -/** - * Get the user-specified pointer associated with a texture - * - * \param texture the texture to query. - * \return the pointer associated with the texture, or NULL if the texture is - * not valid. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_SetTextureUserData - */ -extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture); - -/** - * Update the given texture rectangle with new pixel data. - * - * The pixel data must be in the pixel format of the texture. Use - * SDL_QueryTexture() to query the pixel format of the texture. - * - * This is a fairly slow function, intended for use with static textures that - * do not change often. - * - * If the texture is intended to be updated often, it is preferred to create - * the texture as streaming and use the locking functions referenced below. - * While this function will work with streaming textures, for optimization - * reasons you may not get the pixels back if you lock the texture afterward. - * - * \param texture the texture to update. - * \param rect an SDL_Rect structure representing the area to update, or NULL - * to update the entire texture. - * \param pixels the raw pixel data in the format of the texture. - * \param pitch the number of bytes in a row of pixel data, including padding - * between lines. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateTexture - * \sa SDL_LockTexture - * \sa SDL_UnlockTexture - */ -extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, - const SDL_Rect * rect, - const void *pixels, int pitch); - -/** - * Update a rectangle within a planar YV12 or IYUV texture with new pixel - * data. - * - * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous - * block of Y and U/V planes in the proper order, but this function is - * available if your pixel data is not contiguous. - * - * \param texture the texture to update. - * \param rect a pointer to the rectangle of pixels to update, or NULL to - * update the entire texture. - * \param Yplane the raw pixel data for the Y plane. - * \param Ypitch the number of bytes between rows of pixel data for the Y - * plane. - * \param Uplane the raw pixel data for the U plane. - * \param Upitch the number of bytes between rows of pixel data for the U - * plane. - * \param Vplane the raw pixel data for the V plane. - * \param Vpitch the number of bytes between rows of pixel data for the V - * plane. - * \returns 0 on success or -1 if the texture is not valid; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.1. - * - * \sa SDL_UpdateTexture - */ -extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, - const SDL_Rect * rect, - const Uint8 *Yplane, int Ypitch, - const Uint8 *Uplane, int Upitch, - const Uint8 *Vplane, int Vpitch); - -/** - * Update a rectangle within a planar NV12 or NV21 texture with new pixels. - * - * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous - * block of NV12/21 planes in the proper order, but this function is available - * if your pixel data is not contiguous. - * - * \param texture the texture to update. - * \param rect a pointer to the rectangle of pixels to update, or NULL to - * update the entire texture. - * \param Yplane the raw pixel data for the Y plane. - * \param Ypitch the number of bytes between rows of pixel data for the Y - * plane. - * \param UVplane the raw pixel data for the UV plane. - * \param UVpitch the number of bytes between rows of pixel data for the UV - * plane. - * \return 0 on success, or -1 if the texture is not valid. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture, - const SDL_Rect * rect, - const Uint8 *Yplane, int Ypitch, - const Uint8 *UVplane, int UVpitch); - -/** - * Lock a portion of the texture for **write-only** pixel access. - * - * As an optimization, the pixels made available for editing don't necessarily - * contain the old texture data. This is a write-only operation, and if you - * need to keep a copy of the texture data you should do that at the - * application level. - * - * You must use SDL_UnlockTexture() to unlock the pixels and apply any - * changes. - * - * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING`. - * \param rect an SDL_Rect structure representing the area to lock for access; - * NULL to lock the entire texture. - * \param pixels this is filled in with a pointer to the locked pixels, - * appropriately offset by the locked area. - * \param pitch this is filled in with the pitch of the locked pixels; the - * pitch is the length of one row in bytes. - * \returns 0 on success or a negative error code if the texture is not valid - * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_UnlockTexture - */ -extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, - const SDL_Rect * rect, - void **pixels, int *pitch); - -/** - * Lock a portion of the texture for **write-only** pixel access, and expose - * it as a SDL surface. - * - * Besides providing an SDL_Surface instead of raw pixel data, this function - * operates like SDL_LockTexture. - * - * As an optimization, the pixels made available for editing don't necessarily - * contain the old texture data. This is a write-only operation, and if you - * need to keep a copy of the texture data you should do that at the - * application level. - * - * You must use SDL_UnlockTexture() to unlock the pixels and apply any - * changes. - * - * The returned surface is freed internally after calling SDL_UnlockTexture() - * or SDL_DestroyTexture(). The caller should not free it. - * - * \param texture the texture to lock for access, which was created with - * `SDL_TEXTUREACCESS_STREAMING`. - * \param rect a pointer to the rectangle to lock for access. If the rect is - * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns 0 on success, or -1 if the texture is not valid or was not created - * with `SDL_TEXTUREACCESS_STREAMING`. - * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_LockTexture - * \sa SDL_UnlockTexture - */ -extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, - const SDL_Rect *rect, - SDL_Surface **surface); - -/** - * Unlock a texture, uploading the changes to video memory, if needed. - * - * **Warning**: Please note that SDL_LockTexture() is intended to be - * write-only; it will not guarantee the previous contents of the texture will - * be provided. You must fully initialize any area of a texture that you lock - * before unlocking it, as the pixels might otherwise be uninitialized memory. - * - * Which is to say: locking and immediately unlocking a texture can result in - * corrupted textures, depending on the renderer in use. - * - * \param texture a texture locked by SDL_LockTexture(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockTexture - */ -extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); - -/** - * Determine whether a renderer supports the use of render targets. - * - * \param renderer the renderer that will be checked. - * \returns SDL_TRUE if supported or SDL_FALSE if not. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRenderTarget - */ -extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer); - -/** - * Set a texture as the current rendering target. - * - * Before using this function, you should check the - * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if - * render targets are supported. - * - * The default render target is the window for which the renderer was created. - * To stop rendering to a texture and render to the window again, call this - * function with a NULL `texture`. This will reset the renderer's viewport, - * clipping rectangle, and scaling settings to the state they were in before - * setting a non-NULL `texture` target, losing any changes made in the - * meantime. - * - * \param renderer the rendering context. - * \param texture the targeted texture, which must be created with the - * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the - * window instead of a texture. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRenderTarget - */ -extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, - SDL_Texture *texture); - -/** - * Get the current render target. - * - * The default render target is the window for which the renderer was created, - * and is reported as NULL here. - * - * \param renderer the rendering context. - * \returns the current render target or NULL for the default render target. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRenderTarget - */ -extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer); - -/** - * Set a device independent resolution for rendering. - * - * This function uses the viewport and scaling functionality to allow a fixed - * logical resolution for rendering, regardless of the actual output - * resolution. If the actual output resolution doesn't have the same aspect - * ratio the output rendering will be centered within the output display. - * - * If the output display is a window, mouse and touch events in the window - * will be filtered and scaled so they seem to arrive within the logical - * resolution. The SDL_HINT_MOUSE_RELATIVE_SCALING hint controls whether - * relative motion events are also scaled. - * - * If this function results in scaling or subpixel drawing by the rendering - * backend, it will be handled using the appropriate quality hints. - * - * \param renderer the renderer for which resolution should be set. - * \param w the width of the logical resolution. - * \param h the height of the logical resolution. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderGetLogicalSize - */ -extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h); - -/** - * Get device independent resolution for rendering. - * - * When using the main rendering target (eg no target texture is set): this - * may return 0 for `w` and `h` if the SDL_Renderer has never had its logical - * size set by SDL_RenderSetLogicalSize(). Otherwise it returns the logical - * width and height. - * - * When using a target texture: Never return 0 for `w` and `h` at first. Then - * it returns the logical width and height that are set. - * - * \param renderer a rendering context. - * \param w an int to be filled with the width. - * \param h an int to be filled with the height. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderSetLogicalSize - */ -extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h); - -/** - * Set whether to force integer scales for resolution-independent rendering. - * - * This function restricts the logical viewport to integer values - that is, - * when a resolution is between two multiples of a logical size, the viewport - * size is rounded down to the lower multiple. - * - * \param renderer the renderer for which integer scaling should be set. - * \param enable enable or disable the integer scaling for rendering. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_RenderGetIntegerScale - * \sa SDL_RenderSetLogicalSize - */ -extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, - SDL_bool enable); - -/** - * Get whether integer scales are forced for resolution-independent rendering. - * - * \param renderer the renderer from which integer scaling should be queried. - * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_RenderSetIntegerScale - */ -extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer); - -/** - * Set the drawing area for rendering on the current target. - * - * When the window is resized, the viewport is reset to fill the entire new - * window size. - * - * \param renderer the rendering context. - * \param rect the SDL_Rect structure representing the drawing area, or NULL - * to set the viewport to the entire target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderGetViewport - */ -extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, - const SDL_Rect * rect); - -/** - * Get the drawing area for the current target. - * - * \param renderer the rendering context. - * \param rect an SDL_Rect structure filled in with the current drawing area. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderSetViewport - */ -extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, - SDL_Rect * rect); - -/** - * Set the clip rectangle for rendering on the specified target. - * - * \param renderer the rendering context for which clip rectangle should be - * set. - * \param rect an SDL_Rect structure representing the clip area, relative to - * the viewport, or NULL to disable clipping. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderGetClipRect - * \sa SDL_RenderIsClipEnabled - */ -extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, - const SDL_Rect * rect); - -/** - * Get the clip rectangle for the current target. - * - * \param renderer the rendering context from which clip rectangle should be - * queried. - * \param rect an SDL_Rect structure filled in with the current clipping area - * or an empty rectangle if clipping is disabled. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderIsClipEnabled - * \sa SDL_RenderSetClipRect - */ -extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer, - SDL_Rect * rect); - -/** - * Get whether clipping is enabled on the given renderer. - * - * \param renderer the renderer from which clip state should be queried. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_RenderGetClipRect - * \sa SDL_RenderSetClipRect - */ -extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer); - - -/** - * Set the drawing scale for rendering on the current target. - * - * The drawing coordinates are scaled by the x/y scaling factors before they - * are used by the renderer. This allows resolution independent drawing with a - * single coordinate system. - * - * If this results in scaling or subpixel drawing by the rendering backend, it - * will be handled using the appropriate quality hints. For best results use - * integer scaling factors. - * - * \param renderer a rendering context. - * \param scaleX the horizontal scaling factor. - * \param scaleY the vertical scaling factor. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderGetScale - * \sa SDL_RenderSetLogicalSize - */ -extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, - float scaleX, float scaleY); - -/** - * Get the drawing scale for the current target. - * - * \param renderer the renderer from which drawing scale should be queried. - * \param scaleX a pointer filled in with the horizontal scaling factor. - * \param scaleY a pointer filled in with the vertical scaling factor. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderSetScale - */ -extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, - float *scaleX, float *scaleY); - -/** - * Get logical coordinates of point in renderer when given real coordinates of - * point in window. - * - * Logical coordinates will differ from real coordinates when render is scaled - * and logical renderer size set - * - * \param renderer the renderer from which the logical coordinates should be - * calculated. - * \param windowX the real X coordinate in the window. - * \param windowY the real Y coordinate in the window. - * \param logicalX the pointer filled with the logical x coordinate. - * \param logicalY the pointer filled with the logical y coordinate. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_RenderGetScale - * \sa SDL_RenderSetScale - * \sa SDL_RenderGetLogicalSize - * \sa SDL_RenderSetLogicalSize - */ -extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer, - int windowX, int windowY, - float *logicalX, float *logicalY); - - -/** - * Get real coordinates of point in window when given logical coordinates of - * point in renderer. - * - * Logical coordinates will differ from real coordinates when render is scaled - * and logical renderer size set - * - * \param renderer the renderer from which the window coordinates should be - * calculated. - * \param logicalX the logical x coordinate. - * \param logicalY the logical y coordinate. - * \param windowX the pointer filled with the real X coordinate in the window. - * \param windowY the pointer filled with the real Y coordinate in the window. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_RenderGetScale - * \sa SDL_RenderSetScale - * \sa SDL_RenderGetLogicalSize - * \sa SDL_RenderSetLogicalSize - */ -extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer, - float logicalX, float logicalY, - int *windowX, int *windowY); - -/** - * Set the color used for drawing operations (Rect, Line and Clear). - * - * Set the color for drawing or filling rectangles, lines, and points, and for - * SDL_RenderClear(). - * - * \param renderer the rendering context. - * \param r the red value used to draw on the rendering target. - * \param g the green value used to draw on the rendering target. - * \param b the blue value used to draw on the rendering target. - * \param a the alpha value used to draw on the rendering target; usually - * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to - * specify how the alpha channel is used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRenderDrawColor - * \sa SDL_RenderClear - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - */ -extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, - Uint8 r, Uint8 g, Uint8 b, - Uint8 a); - -/** - * Get the color used for drawing operations (Rect, Line and Clear). - * - * \param renderer the rendering context. - * \param r a pointer filled in with the red value used to draw on the - * rendering target. - * \param g a pointer filled in with the green value used to draw on the - * rendering target. - * \param b a pointer filled in with the blue value used to draw on the - * rendering target. - * \param a a pointer filled in with the alpha value used to draw on the - * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer, - Uint8 * r, Uint8 * g, Uint8 * b, - Uint8 * a); - -/** - * Set the blend mode used for drawing operations (Fill and Line). - * - * If the blend mode is not supported, the closest supported mode is chosen. - * - * \param renderer the rendering context. - * \param blendMode the SDL_BlendMode to use for blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRenderDrawBlendMode - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - */ -extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, - SDL_BlendMode blendMode); - -/** - * Get the blend mode used for drawing operations. - * - * \param renderer the rendering context. - * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRenderDrawBlendMode - */ -extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, - SDL_BlendMode *blendMode); - -/** - * Clear the current rendering target with the drawing color. - * - * This function clears the entire rendering target, ignoring the viewport and - * the clip rectangle. - * - * \param renderer the rendering context. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); - -/** - * Draw a point on the current rendering target. - * - * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple, - * use SDL_RenderDrawPoints() instead. - * - * \param renderer the rendering context. - * \param x the x coordinate of the point. - * \param y the y coordinate of the point. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, - int x, int y); - -/** - * Draw multiple points on the current rendering target. - * - * \param renderer the rendering context. - * \param points an array of SDL_Point structures that represent the points to - * draw. - * \param count the number of points to draw. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, - const SDL_Point * points, - int count); - -/** - * Draw a line on the current rendering target. - * - * SDL_RenderDrawLine() draws the line to include both end points. If you want - * to draw multiple, connecting lines use SDL_RenderDrawLines() instead. - * - * \param renderer the rendering context. - * \param x1 the x coordinate of the start point. - * \param y1 the y coordinate of the start point. - * \param x2 the x coordinate of the end point. - * \param y2 the y coordinate of the end point. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, - int x1, int y1, int x2, int y2); - -/** - * Draw a series of connected lines on the current rendering target. - * - * \param renderer the rendering context. - * \param points an array of SDL_Point structures representing points along - * the lines. - * \param count the number of points, drawing count-1 lines. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, - const SDL_Point * points, - int count); - -/** - * Draw a rectangle on the current rendering target. - * - * \param renderer the rendering context. - * \param rect an SDL_Rect structure representing the rectangle to draw, or - * NULL to outline the entire rendering target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, - const SDL_Rect * rect); - -/** - * Draw some number of rectangles on the current rendering target. - * - * \param renderer the rendering context. - * \param rects an array of SDL_Rect structures representing the rectangles to - * be drawn. - * \param count the number of rectangles. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, - const SDL_Rect * rects, - int count); - -/** - * Fill a rectangle on the current rendering target with the drawing color. - * - * The current drawing color is set by SDL_SetRenderDrawColor(), and the - * color's alpha value is ignored unless blending is enabled with the - * appropriate call to SDL_SetRenderDrawBlendMode(). - * - * \param renderer the rendering context. - * \param rect the SDL_Rect structure representing the rectangle to fill, or - * NULL for the entire rendering target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRects - * \sa SDL_RenderPresent - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, - const SDL_Rect * rect); - -/** - * Fill some number of rectangles on the current rendering target with the - * drawing color. - * - * \param renderer the rendering context. - * \param rects an array of SDL_Rect structures representing the rectangles to - * be filled. - * \param count the number of rectangles. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderPresent - */ -extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, - const SDL_Rect * rects, - int count); - -/** - * Copy a portion of the texture to the current rendering target. - * - * The texture is blended with the destination based on its blend mode set - * with SDL_SetTextureBlendMode(). - * - * The texture color is affected based on its color modulation set by - * SDL_SetTextureColorMod(). - * - * The texture alpha is affected based on its alpha modulation set by - * SDL_SetTextureAlphaMod(). - * - * \param renderer the rendering context. - * \param texture the source texture. - * \param srcrect the source SDL_Rect structure or NULL for the entire - * texture. - * \param dstrect the destination SDL_Rect structure or NULL for the entire - * rendering target; the texture will be stretched to fill the - * given rectangle. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderCopyEx - * \sa SDL_SetTextureAlphaMod - * \sa SDL_SetTextureBlendMode - * \sa SDL_SetTextureColorMod - */ -extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, - SDL_Texture * texture, - const SDL_Rect * srcrect, - const SDL_Rect * dstrect); - -/** - * Copy a portion of the texture to the current rendering, with optional - * rotation and flipping. - * - * Copy a portion of the texture to the current rendering target, optionally - * rotating it by angle around the given center and also flipping it - * top-bottom and/or left-right. - * - * The texture is blended with the destination based on its blend mode set - * with SDL_SetTextureBlendMode(). - * - * The texture color is affected based on its color modulation set by - * SDL_SetTextureColorMod(). - * - * The texture alpha is affected based on its alpha modulation set by - * SDL_SetTextureAlphaMod(). - * - * \param renderer the rendering context. - * \param texture the source texture. - * \param srcrect the source SDL_Rect structure or NULL for the entire - * texture. - * \param dstrect the destination SDL_Rect structure or NULL for the entire - * rendering target. - * \param angle an angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction. - * \param center a pointer to a point indicating the point around which - * dstrect will be rotated (if NULL, rotation will be done - * around `dstrect.w / 2`, `dstrect.h / 2`). - * \param flip a SDL_RendererFlip value stating which flipping actions should - * be performed on the texture. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RenderCopy - * \sa SDL_SetTextureAlphaMod - * \sa SDL_SetTextureBlendMode - * \sa SDL_SetTextureColorMod - */ -extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, - SDL_Texture * texture, - const SDL_Rect * srcrect, - const SDL_Rect * dstrect, - const double angle, - const SDL_Point *center, - const SDL_RendererFlip flip); - - -/** - * Draw a point on the current rendering target at subpixel precision. - * - * \param renderer The renderer which should draw a point. - * \param x The x coordinate of the point. - * \param y The y coordinate of the point. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, - float x, float y); - -/** - * Draw multiple points on the current rendering target at subpixel precision. - * - * \param renderer The renderer which should draw multiple points. - * \param points The points to draw. - * \param count The number of points to draw. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, - const SDL_FPoint * points, - int count); - -/** - * Draw a line on the current rendering target at subpixel precision. - * - * \param renderer The renderer which should draw a line. - * \param x1 The x coordinate of the start point. - * \param y1 The y coordinate of the start point. - * \param x2 The x coordinate of the end point. - * \param y2 The y coordinate of the end point. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, - float x1, float y1, float x2, float y2); - -/** - * Draw a series of connected lines on the current rendering target at - * subpixel precision. - * - * \param renderer The renderer which should draw multiple lines. - * \param points The points along the lines. - * \param count The number of points, drawing count-1 lines. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, - const SDL_FPoint * points, - int count); - -/** - * Draw a rectangle on the current rendering target at subpixel precision. - * - * \param renderer The renderer which should draw a rectangle. - * \param rect A pointer to the destination rectangle, or NULL to outline the - * entire rendering target. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, - const SDL_FRect * rect); - -/** - * Draw some number of rectangles on the current rendering target at subpixel - * precision. - * - * \param renderer The renderer which should draw multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, - const SDL_FRect * rects, - int count); - -/** - * Fill a rectangle on the current rendering target with the drawing color at - * subpixel precision. - * - * \param renderer The renderer which should fill a rectangle. - * \param rect A pointer to the destination rectangle, or NULL for the entire - * rendering target. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, - const SDL_FRect * rect); - -/** - * Fill some number of rectangles on the current rendering target with the - * drawing color at subpixel precision. - * - * \param renderer The renderer which should fill multiple rectangles. - * \param rects A pointer to an array of destination rectangles. - * \param count The number of rectangles. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, - const SDL_FRect * rects, - int count); - -/** - * Copy a portion of the texture to the current rendering target at subpixel - * precision. - * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, - SDL_Texture * texture, - const SDL_Rect * srcrect, - const SDL_FRect * dstrect); - -/** - * Copy a portion of the source texture to the current rendering target, with - * rotation and flipping, at subpixel precision. - * - * \param renderer The renderer which should copy parts of a texture. - * \param texture The source texture. - * \param srcrect A pointer to the source rectangle, or NULL for the entire - * texture. - * \param dstrect A pointer to the destination rectangle, or NULL for the - * entire rendering target. - * \param angle An angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction. - * \param center A pointer to a point indicating the point around which - * dstrect will be rotated (if NULL, rotation will be done - * around dstrect.w/2, dstrect.h/2). - * \param flip An SDL_RendererFlip value stating which flipping actions should - * be performed on the texture. - * \return 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, - SDL_Texture * texture, - const SDL_Rect * srcrect, - const SDL_FRect * dstrect, - const double angle, - const SDL_FPoint *center, - const SDL_RendererFlip flip); - -/** - * Render a list of triangles, optionally using a texture and indices into the - * vertex array Color and alpha modulation is done per vertex - * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). - * - * \param renderer The rendering context. - * \param texture (optional) The SDL texture to use. - * \param vertices Vertices. - * \param num_vertices Number of vertices. - * \param indices (optional) An array of integer indices into the 'vertices' - * array, if NULL all vertices will be rendered in sequential - * order. - * \param num_indices Number of indices. - * \return 0 on success, or -1 if the operation is not supported. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_RenderGeometryRaw - * \sa SDL_Vertex - */ -extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, - SDL_Texture *texture, - const SDL_Vertex *vertices, int num_vertices, - const int *indices, int num_indices); - -/** - * Render a list of triangles, optionally using a texture and indices into the - * vertex arrays Color and alpha modulation is done per vertex - * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). - * - * \param renderer The rendering context. - * \param texture (optional) The SDL texture to use. - * \param xy Vertex positions. - * \param xy_stride Byte size to move from one element to the next element. - * \param color Vertex colors (as SDL_Color). - * \param color_stride Byte size to move from one element to the next element. - * \param uv Vertex normalized texture coordinates. - * \param uv_stride Byte size to move from one element to the next element. - * \param num_vertices Number of vertices. - * \param indices (optional) An array of indices into the 'vertices' arrays, - * if NULL all vertices will be rendered in sequential order. - * \param num_indices Number of indices. - * \param size_indices Index size: 1 (byte), 2 (short), 4 (int). - * \return 0 on success, or -1 if the operation is not supported. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_RenderGeometry - * \sa SDL_Vertex - */ -extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, - SDL_Texture *texture, - const float *xy, int xy_stride, - const SDL_Color *color, int color_stride, - const float *uv, int uv_stride, - int num_vertices, - const void *indices, int num_indices, int size_indices); - -/** - * Read pixels from the current rendering target to an array of pixels. - * - * **WARNING**: This is a very slow operation, and should not be used - * frequently. If you're using this on the main rendering target, it should be - * called after rendering and before SDL_RenderPresent(). - * - * `pitch` specifies the number of bytes between rows in the destination - * `pixels` data. This allows you to write to a subrectangle or have padded - * rows in the destination. Generally, `pitch` should equal the number of - * pixels per row in the `pixels` data times the number of bytes per pixel, - * but it might contain additional padding (for example, 24bit RGB Windows - * Bitmap data pads all rows to multiples of 4 bytes). - * - * \param renderer the rendering context. - * \param rect an SDL_Rect structure representing the area to read, or NULL - * for the entire render target. - * \param format an SDL_PixelFormatEnum value of the desired format of the - * pixel data, or 0 to use the format of the rendering target. - * \param pixels a pointer to the pixel data to copy into. - * \param pitch the pitch of the `pixels` parameter. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, - const SDL_Rect * rect, - Uint32 format, - void *pixels, int pitch); - -/** - * Update the screen with any rendering performed since the previous call. - * - * SDL's rendering functions operate on a backbuffer; that is, calling a - * rendering function such as SDL_RenderDrawLine() does not directly put a - * line on the screen, but rather updates the backbuffer. As such, you compose - * your entire scene and *present* the composed backbuffer to the screen as a - * complete picture. - * - * Therefore, when using SDL's rendering API, one does all drawing intended - * for the frame, and then calls this function once per frame to present the - * final drawing to the user. - * - * The backbuffer should be considered invalidated after each present; do not - * assume that previous contents will exist between frames. You are strongly - * encouraged to call SDL_RenderClear() to initialize the backbuffer before - * starting each new frame's drawing, even if you plan to overwrite every - * pixel. - * - * \param renderer the rendering context. - * - * \threadsafety You may only call this function on the main thread. If this - * happens to work on a background thread on any given platform - * or backend, it's purely by luck and you should not rely on it - * to work next time. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - * \sa SDL_RenderClear - * \sa SDL_RenderDrawLine - * \sa SDL_RenderDrawLines - * \sa SDL_RenderDrawPoint - * \sa SDL_RenderDrawPoints - * \sa SDL_RenderDrawRect - * \sa SDL_RenderDrawRects - * \sa SDL_RenderFillRect - * \sa SDL_RenderFillRects - * \sa SDL_SetRenderDrawBlendMode - * \sa SDL_SetRenderDrawColor - */ -extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer); - -/** - * Destroy the specified texture. - * - * Passing NULL or an otherwise invalid texture will set the SDL error message - * to "Invalid texture". - * - * \param texture the texture to destroy. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateTexture - * \sa SDL_CreateTextureFromSurface - */ -extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture); - -/** - * Destroy the rendering context for a window and free associated textures. - * - * If `renderer` is NULL, this function will return immediately after setting - * the SDL error message to "Invalid renderer". See SDL_GetError(). - * - * \param renderer the rendering context. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRenderer - */ -extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); - -/** - * Force the rendering context to flush any pending commands to the underlying - * rendering API. - * - * You do not need to (and in fact, shouldn't) call this function unless you - * are planning to call into OpenGL/Direct3D/Metal/whatever directly in - * addition to using an SDL_Renderer. - * - * This is for a very-specific case: if you are using SDL's render API, you - * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set - * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever - * calls in addition to SDL render API calls. If all of this applies, you - * should call SDL_RenderFlush() between calls to SDL's render API and the - * low-level API you're using in cooperation. - * - * In all other cases, you can ignore this function. This is only here to get - * maximum performance out of a specific situation. In all other cases, SDL - * will do the right thing, perhaps at a performance loss. - * - * This function is first available in SDL 2.0.10, and is not needed in 2.0.9 - * and earlier, as earlier versions did not queue rendering commands at all, - * instead flushing them to the OS immediately. - * - * \param renderer the rendering context. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); - - -/** - * Bind an OpenGL/ES/ES2 texture to the current context. - * - * This is for use with OpenGL instructions when rendering OpenGL primitives - * directly. - * - * If not NULL, `texw` and `texh` will be filled with the width and height - * values suitable for the provided texture. In most cases, both will be 1.0, - * however, on systems that support the GL_ARB_texture_rectangle extension, - * these values will actually be the pixel width and height used to create the - * texture, so this factor needs to be taken into account when providing - * texture coordinates to OpenGL. - * - * You need a renderer to create an SDL_Texture, therefore you can only use - * this function with an implicit OpenGL context from SDL_CreateRenderer(), - * not with your own OpenGL context. If you need control over your OpenGL - * context, you need to write your own texture-loading methods. - * - * Also note that SDL may upload RGB textures as BGR (or vice-versa), and - * re-order the color channels in the shaders phase, so the uploaded texture - * may have swapped color channels. - * - * \param texture the texture to bind to the current OpenGL/ES/ES2 context. - * \param texw a pointer to a float value which will be filled with the - * texture width or NULL if you don't need that value. - * \param texh a pointer to a float value which will be filled with the - * texture height or NULL if you don't need that value. - * \returns 0 on success, or -1 if the operation is not supported; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_MakeCurrent - * \sa SDL_GL_UnbindTexture - */ -extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh); - -/** - * Unbind an OpenGL/ES/ES2 texture from the current context. - * - * See SDL_GL_BindTexture() for examples on how to use these functions - * - * \param texture the texture to unbind from the current OpenGL/ES/ES2 - * context. - * \returns 0 on success, or -1 if the operation is not supported. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_BindTexture - * \sa SDL_GL_MakeCurrent - */ -extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); - -/** - * Get the CAMetalLayer associated with the given Metal renderer. - * - * This function returns `void *`, so SDL doesn't have to include Metal's - * headers, but it can be safely cast to a `CAMetalLayer *`. - * - * \param renderer The renderer to query. - * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a - * Metal renderer. - * - * \since This function is available since SDL 2.0.8. - * - * \sa SDL_RenderGetMetalCommandEncoder - */ -extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); - -/** - * Get the Metal command encoder for the current frame - * - * This function returns `void *`, so SDL doesn't have to include Metal's - * headers, but it can be safely cast to an `id`. - * - * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give - * SDL a drawable to render to, which might happen if the window is - * hidden/minimized/offscreen. This doesn't apply to command encoders for - * render targets, just the window's backbuffer. Check your return values! - * - * \param renderer The renderer to query. - * \returns an `id` on success, or NULL if the - * renderer isn't a Metal renderer or there was an error. - * - * \since This function is available since SDL 2.0.8. - * - * \sa SDL_RenderGetMetalLayer - */ -extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer); - -/** - * Toggle VSync of the given renderer. - * - * \param renderer The renderer to toggle. - * \param vsync 1 for on, 0 for off. All other values are reserved. - * \returns a 0 int on success, or non-zero on failure. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_RenderSetVSync(SDL_Renderer* renderer, int vsync); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_render_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_revision.h b/code/thirdparty/SDL2-2.32.8/include/SDL_revision.h deleted file mode 100644 index 36691f5531..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_revision.h +++ /dev/null @@ -1,6 +0,0 @@ -#ifdef SDL_VENDOR_INFO -#define SDL_REVISION SDL_VENDOR_INFO -#else -#define SDL_REVISION "" -#endif -#define SDL_REVISION_NUMBER 0 diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_rwops.h b/code/thirdparty/SDL2-2.32.8/include/SDL_rwops.h deleted file mode 100644 index 43c1b0ec77..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_rwops.h +++ /dev/null @@ -1,844 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: RWOPS */ - -/** - * # CategoryRWOPS - * - * This file provides a general interface for SDL to read and write data - * streams. It can easily be extended to files, memory, etc. - */ - -#ifndef SDL_rwops_h_ -#define SDL_rwops_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* RWops Types */ -#define SDL_RWOPS_UNKNOWN 0U /**< Unknown stream type */ -#define SDL_RWOPS_WINFILE 1U /**< Win32 file */ -#define SDL_RWOPS_STDFILE 2U /**< Stdio file */ -#define SDL_RWOPS_JNIFILE 3U /**< Android asset */ -#define SDL_RWOPS_MEMORY 4U /**< Memory stream */ -#define SDL_RWOPS_MEMORY_RO 5U /**< Read-Only memory stream */ - -/** - * This is the read/write operation structure -- very basic. - */ -typedef struct SDL_RWops -{ - /** - * Return the size of the file in this rwops, or -1 if unknown - */ - Sint64 (SDLCALL * size) (struct SDL_RWops * context); - - /** - * Seek to `offset` relative to `whence`, one of stdio's whence values: - * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END - * - * \return the final offset in the data stream, or -1 on error. - */ - Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset, - int whence); - - /** - * Read up to `maxnum` objects each of size `size` from the data - * stream to the area pointed at by `ptr`. - * - * \return the number of objects read, or 0 at error or end of file. - */ - size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr, - size_t size, size_t maxnum); - - /** - * Write exactly `num` objects each of size `size` from the area - * pointed at by `ptr` to data stream. - * - * \return the number of objects written, or 0 at error or end of file. - */ - size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr, - size_t size, size_t num); - - /** - * Close and free an allocated SDL_RWops structure. - * - * \return 0 if successful or -1 on write error when flushing data. - */ - int (SDLCALL * close) (struct SDL_RWops * context); - - Uint32 type; - union - { -#if defined(__ANDROID__) - struct - { - void *asset; - } androidio; -#elif defined(__WIN32__) || defined(__GDK__) - struct - { - SDL_bool append; - void *h; - struct - { - void *data; - size_t size; - size_t left; - } buffer; - } windowsio; -#endif - -#ifdef HAVE_STDIO_H - struct - { - SDL_bool autoclose; - FILE *fp; - } stdio; -#endif - struct - { - Uint8 *base; - Uint8 *here; - Uint8 *stop; - } mem; - struct - { - void *data1; - void *data2; - } unknown; - } hidden; - -} SDL_RWops; - - -/** - * \name RWFrom functions - * - * Functions to create SDL_RWops structures from various data streams. - */ -/* @{ */ - -/** - * Use this function to create a new SDL_RWops structure for reading from - * and/or writing to a named file. - * - * The `mode` string is treated roughly the same as in a call to the C - * library's fopen(), even if SDL doesn't happen to use fopen() behind the - * scenes. - * - * Available `mode` strings: - * - * - "r": Open a file for reading. The file must exist. - * - "w": Create an empty file for writing. If a file with the same name - * already exists its content is erased and the file is treated as a new - * empty file. - * - "a": Append to a file. Writing operations append data at the end of the - * file. The file is created if it does not exist. - * - "r+": Open a file for update both reading and writing. The file must - * exist. - * - "w+": Create an empty file for both reading and writing. If a file with - * the same name already exists its content is erased and the file is - * treated as a new empty file. - * - "a+": Open a file for reading and appending. All writing operations are - * performed at the end of the file, protecting the previous content to be - * overwritten. You can reposition (fseek, rewind) the internal pointer to - * anywhere in the file for reading, but writing operations will move it - * back to the end of file. The file is created if it does not exist. - * - * **NOTE**: In order to open a file as a binary file, a "b" character has to - * be included in the `mode` string. This additional "b" character can either - * be appended at the end of the string (thus making the following compound - * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the - * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). - * Additional characters may follow the sequence, although they should have no - * effect. For example, "t" is sometimes appended to make explicit the file is - * a text file. - * - * This function supports Unicode filenames, but they must be encoded in UTF-8 - * format, regardless of the underlying operating system. - * - * As a fallback, SDL_RWFromFile() will transparently open a matching filename - * in an Android app's `assets`. - * - * Closing the SDL_RWops will close the file handle SDL is holding internally. - * - * \param file a UTF-8 string representing the filename to open. - * \param mode an ASCII string representing the mode to be used for opening - * the file. - * \returns a pointer to the SDL_RWops structure that is created, or NULL on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWtell - * \sa SDL_RWwrite - */ -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file, - const char *mode); - -#ifdef HAVE_STDIO_H - -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose); - -#else - -/** - * Use this function to create an SDL_RWops structure from a standard I/O file - * pointer (stdio.h's `FILE*`). - * - * This function is not available on Windows, since files opened in an - * application on that platform cannot be used by a dynamically linked - * library. - * - * On some platforms, the first parameter is a `void*`, on others, it's a - * `FILE*`, depending on what system headers are available to SDL. It is - * always intended to be the `FILE*` type from the C runtime's stdio.h. - * - * \param fp the `FILE*` that feeds the SDL_RWops stream. - * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops, - * SDL_FALSE to leave the `FILE*` open when the RWops is - * closed. - * \returns a pointer to the SDL_RWops structure that is created, or NULL on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWtell - * \sa SDL_RWwrite - */ -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp, - SDL_bool autoclose); -#endif - -/** - * Use this function to prepare a read-write memory buffer for use with - * SDL_RWops. - * - * This function sets up an SDL_RWops struct based on a memory area of a - * certain size, for both read and write access. - * - * This memory buffer is not copied by the RWops; the pointer you provide must - * remain valid until you close the stream. Closing the stream will not free - * the original buffer. - * - * If you need to make sure the RWops never writes to the memory buffer, you - * should use SDL_RWFromConstMem() with a read-only buffer of memory instead. - * - * \param mem a pointer to a buffer to feed an SDL_RWops stream. - * \param size the buffer size, in bytes. - * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWtell - * \sa SDL_RWwrite - */ -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); - -/** - * Use this function to prepare a read-only memory buffer for use with RWops. - * - * This function sets up an SDL_RWops struct based on a memory area of a - * certain size. It assumes the memory area is not writable. - * - * Attempting to write to this RWops stream will report an error without - * writing to the memory buffer. - * - * This memory buffer is not copied by the RWops; the pointer you provide must - * remain valid until you close the stream. Closing the stream will not free - * the original buffer. - * - * If you need to write to a memory buffer, you should use SDL_RWFromMem() - * with a writable buffer of memory instead. - * - * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream. - * \param size the buffer size, in bytes. - * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWtell - */ -extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem, - int size); - -/* @} *//* RWFrom functions */ - - -/** - * Use this function to allocate an empty, unpopulated SDL_RWops structure. - * - * Applications do not need to use this function unless they are providing - * their own SDL_RWops implementation. If you just need a SDL_RWops to - * read/write a common data source, you should use the built-in - * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc. - * - * You must free the returned pointer with SDL_FreeRW(). Depending on your - * operating system and compiler, there may be a difference between the - * malloc() and free() your program uses and the versions SDL calls - * internally. Trying to mix the two can cause crashing such as segmentation - * faults. Since all SDL_RWops must free themselves when their **close** - * method is called, all SDL_RWops must be allocated through this function, so - * they can all be freed correctly with SDL_FreeRW(). - * - * \returns a pointer to the allocated memory on success, or NULL on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeRW - */ -extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); - -/** - * Use this function to free an SDL_RWops structure allocated by - * SDL_AllocRW(). - * - * Applications do not need to use this function unless they are providing - * their own SDL_RWops implementation. If you just need a SDL_RWops to - * read/write a common data source, you should use the built-in - * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc, and - * call the **close** method on those SDL_RWops pointers when you are done - * with them. - * - * Only use SDL_FreeRW() on pointers returned by SDL_AllocRW(). The pointer is - * invalid as soon as this function returns. Any extra memory allocated during - * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must - * be responsible for managing that memory in their **close** method. - * - * \param area the SDL_RWops structure to be freed. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocRW - */ -extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); - -/* Possible `whence` values for SDL_RWops seeking... */ -#define RW_SEEK_SET 0 /**< Seek from the beginning of data */ -#define RW_SEEK_CUR 1 /**< Seek relative to current read point */ -#define RW_SEEK_END 2 /**< Seek relative to the end of data */ - -/** - * Use this function to get the size of the data stream in an SDL_RWops. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context the SDL_RWops to get the size of the data stream from. - * \returns the size of the data stream in the SDL_RWops on success, -1 if - * unknown or a negative error code on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); - -/** - * Seek within an SDL_RWops data stream. - * - * This function seeks to byte `offset`, relative to `whence`. - * - * `whence` may be any of the following values: - * - * - `RW_SEEK_SET`: seek from the beginning of data - * - `RW_SEEK_CUR`: seek relative to current read point - * - `RW_SEEK_END`: seek relative to the end of data - * - * If this stream can not seek, it will return -1. - * - * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's - * `seek` method appropriately, to simplify application development. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context a pointer to an SDL_RWops structure. - * \param offset an offset in bytes, relative to **whence** location; can be - * negative. - * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`. - * \returns the final offset in the data stream after the seek or -1 on error. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWtell - * \sa SDL_RWwrite - */ -extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, - Sint64 offset, int whence); - -/** - * Determine the current read/write offset in an SDL_RWops data stream. - * - * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek` - * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify - * application development. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context a SDL_RWops data stream object from which to get the current - * offset. - * \returns the current offset in the stream, or -1 if the information can not - * be determined. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWwrite - */ -extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context); - -/** - * Read from a data source. - * - * This function reads up to `maxnum` objects each of size `size` from the - * data source to the area pointed at by `ptr`. This function may read less - * objects than requested. It will return zero when there has been an error or - * the data stream is completely read. - * - * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's - * `read` method appropriately, to simplify application development. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context a pointer to an SDL_RWops structure. - * \param ptr a pointer to a buffer to read data into. - * \param size the size of each object to read, in bytes. - * \param maxnum the maximum number of objects to be read. - * \returns the number of objects read, or 0 at error or end of file; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWseek - * \sa SDL_RWwrite - */ -extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, - void *ptr, size_t size, - size_t maxnum); - -/** - * Write to an SDL_RWops data stream. - * - * This function writes exactly `num` objects each of size `size` from the - * area pointed at by `ptr` to the stream. If this fails for any reason, it'll - * return less than `num` to demonstrate how far the write progressed. On - * success, it returns `num`. - * - * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's - * `write` method appropriately, to simplify application development. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context a pointer to an SDL_RWops structure. - * \param ptr a pointer to a buffer containing data to write. - * \param size the size of an object to write, in bytes. - * \param num the number of objects to write. - * \returns the number of objects written, which will be less than **num** on - * error; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_RWclose - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - */ -extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, - const void *ptr, size_t size, - size_t num); - -/** - * Close and free an allocated SDL_RWops structure. - * - * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any - * resources used by the stream and frees the SDL_RWops itself with - * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to - * flush to its output (e.g. to disk). - * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_RWops is still invalid once this function returns. - * - * Prior to SDL 2.0.10, this function was a macro. - * - * \param context SDL_RWops structure to close. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.10. - * - * \sa SDL_RWFromConstMem - * \sa SDL_RWFromFile - * \sa SDL_RWFromFP - * \sa SDL_RWFromMem - * \sa SDL_RWread - * \sa SDL_RWseek - * \sa SDL_RWwrite - */ -extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context); - -/** - * Load all the data from an SDL data stream. - * - * The data is allocated with a zero byte at the end (null terminated) for - * convenience. This extra byte is not included in the value reported via - * `datasize`. - * - * The data should be freed with SDL_free(). - * - * \param src the SDL_RWops to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning. - * \returns the data, or NULL if there was an error. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src, - size_t *datasize, - int freesrc); - -/** - * Load all the data from a file path. - * - * The data is allocated with a zero byte at the end (null terminated) for - * convenience. This extra byte is not included in the value reported via - * `datasize`. - * - * The data should be freed with SDL_free(). - * - * Prior to SDL 2.0.10, this function was a macro wrapping around - * SDL_LoadFile_RW. - * - * \param file the path to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \returns the data, or NULL if there was an error. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); - -/** - * \name Read endian functions - * - * Read an item of the specified endianness and return in native format. - */ -/* @{ */ - -/** - * Use this function to read a byte from an SDL_RWops. - * - * \param src the SDL_RWops to read from. - * \returns the read byte on success or 0 on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteU8 - */ -extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src); - -/** - * Use this function to read 16 bits of little-endian data from an SDL_RWops - * and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 16 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadBE16 - */ -extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); - -/** - * Use this function to read 16 bits of big-endian data from an SDL_RWops and - * return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 16 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadLE16 - */ -extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); - -/** - * Use this function to read 32 bits of little-endian data from an SDL_RWops - * and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 32 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadBE32 - */ -extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); - -/** - * Use this function to read 32 bits of big-endian data from an SDL_RWops and - * return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 32 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadLE32 - */ -extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); - -/** - * Use this function to read 64 bits of little-endian data from an SDL_RWops - * and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 64 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadBE64 - */ -extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); - -/** - * Use this function to read 64 bits of big-endian data from an SDL_RWops and - * return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \returns 64 bits of data in the native byte order of the platform. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadLE64 - */ -extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); -/* @} *//* Read endian functions */ - -/** - * \name Write endian functions - * - * Write an item of native format to the specified endianness. - */ -/* @{ */ - -/** - * Use this function to write a byte to an SDL_RWops. - * - * \param dst the SDL_RWops to write to. - * \param value the byte value to write. - * \returns 1 on success or 0 on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ReadU8 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value); - -/** - * Use this function to write 16 bits in native format to a SDL_RWops as - * little-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in little-endian - * format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteBE16 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); - -/** - * Use this function to write 16 bits in native format to a SDL_RWops as - * big-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in big-endian format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteLE16 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value); - -/** - * Use this function to write 32 bits in native format to a SDL_RWops as - * little-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in little-endian - * format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteBE32 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); - -/** - * Use this function to write 32 bits in native format to a SDL_RWops as - * big-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in big-endian format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteLE32 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value); - -/** - * Use this function to write 64 bits in native format to a SDL_RWops as - * little-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in little-endian - * format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteBE64 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); - -/** - * Use this function to write 64 bits in native format to a SDL_RWops as - * big-endian data. - * - * SDL byteswaps the data only if necessary, so the application always - * specifies native format, and the data written will be in big-endian format. - * - * \param dst the stream to which data will be written. - * \param value the data to be written, in native format. - * \returns 1 on successful write, 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WriteLE64 - */ -extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value); -/* @} *//* Write endian functions */ - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_rwops_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_shape.h b/code/thirdparty/SDL2-2.32.8/include/SDL_shape.h deleted file mode 100644 index d3560845f8..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_shape.h +++ /dev/null @@ -1,155 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_shape_h_ -#define SDL_shape_h_ - -#include "SDL_stdinc.h" -#include "SDL_pixels.h" -#include "SDL_rect.h" -#include "SDL_surface.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** \file SDL_shape.h - * - * Header file for the shaped window API. - */ - -#define SDL_NONSHAPEABLE_WINDOW -1 -#define SDL_INVALID_SHAPE_ARGUMENT -2 -#define SDL_WINDOW_LACKS_SHAPE -3 - -/** - * Create a window that can be shaped with the specified position, dimensions, - * and flags. - * - * \param title The title of the window, in UTF-8 encoding. - * \param x The x position of the window, SDL_WINDOWPOS_CENTERED, or - * SDL_WINDOWPOS_UNDEFINED. - * \param y The y position of the window, SDL_WINDOWPOS_CENTERED, or - * SDL_WINDOWPOS_UNDEFINED. - * \param w The width of the window. - * \param h The height of the window. - * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with - * any of the following: SDL_WINDOW_OPENGL, - * SDL_WINDOW_INPUT_GRABBED, SDL_WINDOW_HIDDEN, - * SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, - * SDL_WINDOW_MINIMIZED, SDL_WINDOW_BORDERLESS is always set, and - * SDL_WINDOW_FULLSCREEN is always unset. - * \return the window created, or NULL if window creation failed. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroyWindow - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags); - -/** - * Return whether the given window is a shaped window. - * - * \param window The window to query for being shaped. - * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if - * the window is unshaped or NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateShapedWindow - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsShapedWindow(const SDL_Window *window); - -/** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. */ -typedef enum { - /** \brief The default mode, a binarized alpha cutoff of 1. */ - ShapeModeDefault, - /** \brief A binarized alpha cutoff with a given integer value. */ - ShapeModeBinarizeAlpha, - /** \brief A binarized alpha cutoff with a given integer value, but with the opposite comparison. */ - ShapeModeReverseBinarizeAlpha, - /** \brief A color key is applied. */ - ShapeModeColorKey -} WindowShapeMode; - -#define SDL_SHAPEMODEALPHA(mode) (mode == ShapeModeDefault || mode == ShapeModeBinarizeAlpha || mode == ShapeModeReverseBinarizeAlpha) - -/** \brief A union containing parameters for shaped windows. */ -typedef union { - /** \brief A cutoff alpha value for binarization of the window shape's alpha channel. */ - Uint8 binarizationCutoff; - SDL_Color colorKey; -} SDL_WindowShapeParams; - -/** \brief A struct that tags the SDL_WindowShapeParams union with an enum describing the type of its contents. */ -typedef struct SDL_WindowShapeMode { - /** \brief The mode of these window-shape parameters. */ - WindowShapeMode mode; - /** \brief Window-shape parameters. */ - SDL_WindowShapeParams parameters; -} SDL_WindowShapeMode; - -/** - * Set the shape and parameters of a shaped window. - * - * \param window The shaped window whose parameters should be set. - * \param shape A surface encoding the desired shape for the window. - * \param shape_mode The parameters to set for the shaped window. - * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape - * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does - * not reference a valid shaped window. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WindowShapeMode - * \sa SDL_GetShapedWindowMode - */ -extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode); - -/** - * Get the shape parameters of a shaped window. - * - * \param window The shaped window whose parameters should be retrieved. - * \param shape_mode An empty shape-mode structure to fill, or NULL to check - * whether the window has a shape. - * \return 0 if the window has a shape and, provided shape_mode was not NULL, - * shape_mode has been filled with the mode data, - * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped - * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a - * shapeable window currently lacking a shape. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_WindowShapeMode - * \sa SDL_SetWindowShape - */ -extern DECLSPEC int SDLCALL SDL_GetShapedWindowMode(SDL_Window *window,SDL_WindowShapeMode *shape_mode); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_shape_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_stdinc.h b/code/thirdparty/SDL2-2.32.8/include/SDL_stdinc.h deleted file mode 100644 index 1854698b60..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_stdinc.h +++ /dev/null @@ -1,873 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: StdInc */ - -/** - * # CategoryStdInc - * - * This is a general header that includes C language support. - */ - -#ifndef SDL_stdinc_h_ -#define SDL_stdinc_h_ - -#include "SDL_config.h" - -#ifdef HAVE_SYS_TYPES_H -#include -#endif -#ifdef HAVE_STDIO_H -#include -#endif -#if defined(STDC_HEADERS) -# include -# include -# include -#else -# if defined(HAVE_STDLIB_H) -# include -# elif defined(HAVE_MALLOC_H) -# include -# endif -# if defined(HAVE_STDDEF_H) -# include -# endif -# if defined(HAVE_STDARG_H) -# include -# endif -#endif -#ifdef HAVE_STRING_H -# if !defined(STDC_HEADERS) && defined(HAVE_MEMORY_H) -# include -# endif -# include -#endif -#ifdef HAVE_STRINGS_H -# include -#endif -#ifdef HAVE_WCHAR_H -# include -#endif -#if defined(HAVE_INTTYPES_H) -# include -#elif defined(HAVE_STDINT_H) -# include -#endif -#ifdef HAVE_CTYPE_H -# include -#endif -#ifdef HAVE_MATH_H -# if defined(_MSC_VER) -/* Defining _USE_MATH_DEFINES is required to get M_PI to be defined on - Visual Studio. See http://msdn.microsoft.com/en-us/library/4hwaceh6.aspx - for more information. -*/ -# ifndef _USE_MATH_DEFINES -# define _USE_MATH_DEFINES -# endif -# endif -# include -#endif -#ifdef HAVE_FLOAT_H -# include -#endif -#if defined(HAVE_ALLOCA) && !defined(alloca) -# if defined(HAVE_ALLOCA_H) -# include -# elif defined(__GNUC__) -# define alloca __builtin_alloca -# elif defined(_MSC_VER) -# include -# define alloca _alloca -# elif defined(__WATCOMC__) -# include -# elif defined(__BORLANDC__) -# include -# elif defined(__DMC__) -# include -# elif defined(__AIX__) -#pragma alloca -# elif defined(__MRC__) -void *alloca(unsigned); -# else -void *alloca(size_t); -# endif -#endif - -#ifdef SIZE_MAX -# define SDL_SIZE_MAX SIZE_MAX -#else -# define SDL_SIZE_MAX ((size_t) -1) -#endif - -/** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. - */ -#ifdef __has_builtin -#define _SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define _SDL_HAS_BUILTIN(x) 0 -#endif - -/** - * The number of elements in an array. - */ -#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) -#define SDL_TABLESIZE(table) SDL_arraysize(table) - -/** - * Macro useful for building other macros with strings in them - * - * e.g: - * - * ```c - * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") - * ``` - */ -#define SDL_STRINGIFY_ARG(arg) #arg - -/** - * \name Cast operators - * - * Use proper C++ casts when compiled as C++ to be compatible with the option - * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). - */ -/* @{ */ -#ifdef __cplusplus -#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) -#define SDL_static_cast(type, expression) static_cast(expression) -#define SDL_const_cast(type, expression) const_cast(expression) -#else -#define SDL_reinterpret_cast(type, expression) ((type)(expression)) -#define SDL_static_cast(type, expression) ((type)(expression)) -#define SDL_const_cast(type, expression) ((type)(expression)) -#endif -/* @} *//* Cast operators */ - -/* Define a four character code as a Uint32 */ -#define SDL_FOURCC(A, B, C, D) \ - ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ - (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ - (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \ - (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24)) - -/** - * \name Basic data types - */ -/* @{ */ - -#ifdef __CC_ARM -/* ARM's compiler throws warnings if we use an enum: like "SDL_bool x = a < b;" */ -#define SDL_FALSE 0 -#define SDL_TRUE 1 -typedef int SDL_bool; -#else -typedef enum -{ - SDL_FALSE = 0, - SDL_TRUE = 1 -} SDL_bool; -#endif - -/** - * A signed 8-bit integer type. - */ -typedef int8_t Sint8; -#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ -#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ - -/** - * An unsigned 8-bit integer type. - */ -typedef uint8_t Uint8; -#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ -#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ - -/** - * A signed 16-bit integer type. - */ -typedef int16_t Sint16; -#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ -#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ - -/** - * An unsigned 16-bit integer type. - */ -typedef uint16_t Uint16; -#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ -#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ - -/** - * A signed 32-bit integer type. - */ -typedef int32_t Sint32; -#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ -#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ - -/** - * An unsigned 32-bit integer type. - */ -typedef uint32_t Uint32; -#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ -#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ - -/** - * A signed 64-bit integer type. - */ -typedef int64_t Sint64; -#define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ -#define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ - -/** - * An unsigned 64-bit integer type. - */ -typedef uint64_t Uint64; -#define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */ -#define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */ - - -/* @} *//* Basic data types */ - -/** - * \name Floating-point constants - */ -/* @{ */ - -#ifdef FLT_EPSILON -#define SDL_FLT_EPSILON FLT_EPSILON -#else -#define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ -#endif - -/* @} *//* Floating-point constants */ - -/* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. - * (for example win32) */ -#ifndef SDL_PRIs64 -#if defined(__WIN32__) || defined(__GDK__) -#define SDL_PRIs64 "I64d" -#elif defined(PRId64) -#define SDL_PRIs64 PRId64 -#elif defined(__LP64__) && !defined(__APPLE__) && !defined(__EMSCRIPTEN__) -#define SDL_PRIs64 "ld" -#else -#define SDL_PRIs64 "lld" -#endif -#endif -#ifndef SDL_PRIu64 -#if defined(__WIN32__) || defined(__GDK__) -#define SDL_PRIu64 "I64u" -#elif defined(PRIu64) -#define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(__APPLE__) -#define SDL_PRIu64 "lu" -#else -#define SDL_PRIu64 "llu" -#endif -#endif -#ifndef SDL_PRIx64 -#if defined(__WIN32__) || defined(__GDK__) -#define SDL_PRIx64 "I64x" -#elif defined(PRIx64) -#define SDL_PRIx64 PRIx64 -#elif defined(__LP64__) && !defined(__APPLE__) -#define SDL_PRIx64 "lx" -#else -#define SDL_PRIx64 "llx" -#endif -#endif -#ifndef SDL_PRIX64 -#if defined(__WIN32__) || defined(__GDK__) -#define SDL_PRIX64 "I64X" -#elif defined(PRIX64) -#define SDL_PRIX64 PRIX64 -#elif defined(__LP64__) && !defined(__APPLE__) -#define SDL_PRIX64 "lX" -#else -#define SDL_PRIX64 "llX" -#endif -#endif -#ifndef SDL_PRIs32 -#ifdef PRId32 -#define SDL_PRIs32 PRId32 -#else -#define SDL_PRIs32 "d" -#endif -#endif -#ifndef SDL_PRIu32 -#ifdef PRIu32 -#define SDL_PRIu32 PRIu32 -#else -#define SDL_PRIu32 "u" -#endif -#endif -#ifndef SDL_PRIx32 -#ifdef PRIx32 -#define SDL_PRIx32 PRIx32 -#else -#define SDL_PRIx32 "x" -#endif -#endif -#ifndef SDL_PRIX32 -#ifdef PRIX32 -#define SDL_PRIX32 PRIX32 -#else -#define SDL_PRIX32 "X" -#endif -#endif - -/* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS -#define SDL_IN_BYTECAP(x) -#define SDL_INOUT_Z_CAP(x) -#define SDL_OUT_Z_CAP(x) -#define SDL_OUT_CAP(x) -#define SDL_OUT_BYTECAP(x) -#define SDL_OUT_Z_BYTECAP(x) -#define SDL_PRINTF_FORMAT_STRING -#define SDL_SCANF_FORMAT_STRING -#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) -#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) -#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) -#else -#if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ -#include - -#define SDL_IN_BYTECAP(x) _In_bytecount_(x) -#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) -#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) -#define SDL_OUT_CAP(x) _Out_cap_(x) -#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) -#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) - -#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ -#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ -#else -#define SDL_IN_BYTECAP(x) -#define SDL_INOUT_Z_CAP(x) -#define SDL_OUT_Z_CAP(x) -#define SDL_OUT_CAP(x) -#define SDL_OUT_BYTECAP(x) -#define SDL_OUT_Z_BYTECAP(x) -#define SDL_PRINTF_FORMAT_STRING -#define SDL_SCANF_FORMAT_STRING -#endif -#if defined(__GNUC__) -#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) -#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) -#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) -#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) -#else -#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) -#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) -#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) -#endif -#endif /* SDL_DISABLE_ANALYZE_MACROS */ - -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - -/** \cond */ -#ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); -#endif /* DOXYGEN_SHOULD_IGNORE_THIS */ -/** \endcond */ - -/* Check to make sure enums are the size of ints, for structure packing. - For both Watcom C/C++ and Borland C/C++ the compiler option that makes - enums having the size of an int must be enabled. - This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11). -*/ - -/** \cond */ -#ifndef DOXYGEN_SHOULD_IGNORE_THIS -#if !defined(__VITA__) && !defined(__3DS__) -/* TODO: include/SDL_stdinc.h:422: error: size of array 'SDL_dummy_enum' is negative */ -typedef enum -{ - DUMMY_ENUM_VALUE -} SDL_DUMMY_ENUM; - -SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); -#endif -#endif /* DOXYGEN_SHOULD_IGNORE_THIS */ -/** \endcond */ - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef HAVE_ALLOCA -#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) -#define SDL_stack_free(data) -#else -#define SDL_stack_alloc(type, count) (type*)SDL_malloc(sizeof(type)*(count)) -#define SDL_stack_free(data) SDL_free(data) -#endif - -extern DECLSPEC void *SDLCALL SDL_malloc(size_t size); -extern DECLSPEC void *SDLCALL SDL_calloc(size_t nmemb, size_t size); -extern DECLSPEC void *SDLCALL SDL_realloc(void *mem, size_t size); -extern DECLSPEC void SDLCALL SDL_free(void *mem); - -typedef void *(SDLCALL *SDL_malloc_func)(size_t size); -typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); -typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); -typedef void (SDLCALL *SDL_free_func)(void *mem); - -/** - * Get the original set of SDL memory functions - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, - SDL_calloc_func *calloc_func, - SDL_realloc_func *realloc_func, - SDL_free_func *free_func); - -/** - * Get the current set of SDL memory functions - * - * \since This function is available since SDL 2.0.7. - */ -extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, - SDL_calloc_func *calloc_func, - SDL_realloc_func *realloc_func, - SDL_free_func *free_func); - -/** - * Replace SDL's memory allocation functions with a custom set - * - * \since This function is available since SDL 2.0.7. - */ -extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, - SDL_calloc_func calloc_func, - SDL_realloc_func realloc_func, - SDL_free_func free_func); - -/** - * Get the number of outstanding (unfreed) allocations - * - * \since This function is available since SDL 2.0.7. - */ -extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void); - -extern DECLSPEC char *SDLCALL SDL_getenv(const char *name); -extern DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); - -typedef int (SDLCALL *SDL_CompareCallback)(const void *, const void *); -extern DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); -extern DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); - -extern DECLSPEC int SDLCALL SDL_abs(int x); - -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ -#define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) -#define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) -#define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) - -extern DECLSPEC int SDLCALL SDL_isalpha(int x); -extern DECLSPEC int SDLCALL SDL_isalnum(int x); -extern DECLSPEC int SDLCALL SDL_isblank(int x); -extern DECLSPEC int SDLCALL SDL_iscntrl(int x); -extern DECLSPEC int SDLCALL SDL_isdigit(int x); -extern DECLSPEC int SDLCALL SDL_isxdigit(int x); -extern DECLSPEC int SDLCALL SDL_ispunct(int x); -extern DECLSPEC int SDLCALL SDL_isspace(int x); -extern DECLSPEC int SDLCALL SDL_isupper(int x); -extern DECLSPEC int SDLCALL SDL_islower(int x); -extern DECLSPEC int SDLCALL SDL_isprint(int x); -extern DECLSPEC int SDLCALL SDL_isgraph(int x); -extern DECLSPEC int SDLCALL SDL_toupper(int x); -extern DECLSPEC int SDLCALL SDL_tolower(int x); - -extern DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); -extern DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); - -extern DECLSPEC void *SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); - -/* Some safe(r) macros for zero'ing structures... */ -#define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) -#define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) -#define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) - -#define SDL_copyp(dst, src) \ - { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ - SDL_memcpy((dst), (src), sizeof (*(src))) - - -/* Note that memset() is a byte assignment and this is a 32-bit assignment, so they're not directly equivalent. */ -SDL_FORCE_INLINE void SDL_memset4(void *dst, Uint32 val, size_t dwords) -{ -#if defined(__GNUC__) && defined(__i386__) - int u0, u1, u2; - __asm__ __volatile__ ( - "cld \n\t" - "rep ; stosl \n\t" - : "=&D" (u0), "=&a" (u1), "=&c" (u2) - : "0" (dst), "1" (val), "2" (SDL_static_cast(Uint32, dwords)) - : "memory" - ); -#else - size_t _n = (dwords + 3) / 4; - Uint32 *_p = SDL_static_cast(Uint32 *, dst); - Uint32 _val = (val); - if (dwords == 0) { - return; - } - switch (dwords % 4) { - case 0: do { *_p++ = _val; SDL_FALLTHROUGH; - case 3: *_p++ = _val; SDL_FALLTHROUGH; - case 2: *_p++ = _val; SDL_FALLTHROUGH; - case 1: *_p++ = _val; - } while ( --_n ); - } -#endif -} - -extern DECLSPEC void *SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); - -extern DECLSPEC void *SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); -extern DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); - -extern DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); -extern DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); -extern DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); -extern DECLSPEC wchar_t *SDLCALL SDL_wcsdup(const wchar_t *wstr); -extern DECLSPEC wchar_t *SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); - -extern DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); -extern DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); -extern DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); -extern DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t len); - -extern DECLSPEC size_t SDLCALL SDL_strlen(const char *str); -extern DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); -extern DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); -extern DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); -extern DECLSPEC char *SDLCALL SDL_strdup(const char *str); -extern DECLSPEC char *SDLCALL SDL_strrev(char *str); -extern DECLSPEC char *SDLCALL SDL_strupr(char *str); -extern DECLSPEC char *SDLCALL SDL_strlwr(char *str); -extern DECLSPEC char *SDLCALL SDL_strchr(const char *str, int c); -extern DECLSPEC char *SDLCALL SDL_strrchr(const char *str, int c); -extern DECLSPEC char *SDLCALL SDL_strstr(const char *haystack, const char *needle); -extern DECLSPEC char *SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern DECLSPEC char *SDLCALL SDL_strtokr(char *s1, const char *s2, char **saveptr); -extern DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); -extern DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); - -extern DECLSPEC char *SDLCALL SDL_itoa(int value, char *str, int radix); -extern DECLSPEC char *SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern DECLSPEC char *SDLCALL SDL_ltoa(long value, char *str, int radix); -extern DECLSPEC char *SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern DECLSPEC char *SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern DECLSPEC char *SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); - -extern DECLSPEC int SDLCALL SDL_atoi(const char *str); -extern DECLSPEC double SDLCALL SDL_atof(const char *str); -extern DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); -extern DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); -extern DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); - -extern DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); -extern DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); -extern DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); -extern DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t len); - -extern DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); -extern DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); -extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); - -#ifndef HAVE_M_PI -#ifndef M_PI -#define M_PI 3.14159265358979323846264338327950288 /**< pi */ -#endif -#endif - -/** - * Use this function to compute arc cosine of `x`. - * - * The definition of `y = acos(x)` is `x = cos(y)`. - * - * Domain: `-1 <= x <= 1` - * - * Range: `0 <= y <= Pi` - * - * \param x floating point value, in radians. - * \returns arc cosine of `x`. - * - * \since This function is available since SDL 2.0.2. - */ -extern DECLSPEC double SDLCALL SDL_acos(double x); -extern DECLSPEC float SDLCALL SDL_acosf(float x); -extern DECLSPEC double SDLCALL SDL_asin(double x); -extern DECLSPEC float SDLCALL SDL_asinf(float x); -extern DECLSPEC double SDLCALL SDL_atan(double x); -extern DECLSPEC float SDLCALL SDL_atanf(float x); -extern DECLSPEC double SDLCALL SDL_atan2(double y, double x); -extern DECLSPEC float SDLCALL SDL_atan2f(float y, float x); -extern DECLSPEC double SDLCALL SDL_ceil(double x); -extern DECLSPEC float SDLCALL SDL_ceilf(float x); -extern DECLSPEC double SDLCALL SDL_copysign(double x, double y); -extern DECLSPEC float SDLCALL SDL_copysignf(float x, float y); -extern DECLSPEC double SDLCALL SDL_cos(double x); -extern DECLSPEC float SDLCALL SDL_cosf(float x); -extern DECLSPEC double SDLCALL SDL_exp(double x); -extern DECLSPEC float SDLCALL SDL_expf(float x); -extern DECLSPEC double SDLCALL SDL_fabs(double x); -extern DECLSPEC float SDLCALL SDL_fabsf(float x); -extern DECLSPEC double SDLCALL SDL_floor(double x); -extern DECLSPEC float SDLCALL SDL_floorf(float x); -extern DECLSPEC double SDLCALL SDL_trunc(double x); -extern DECLSPEC float SDLCALL SDL_truncf(float x); -extern DECLSPEC double SDLCALL SDL_fmod(double x, double y); -extern DECLSPEC float SDLCALL SDL_fmodf(float x, float y); -extern DECLSPEC double SDLCALL SDL_log(double x); -extern DECLSPEC float SDLCALL SDL_logf(float x); -extern DECLSPEC double SDLCALL SDL_log10(double x); -extern DECLSPEC float SDLCALL SDL_log10f(float x); -extern DECLSPEC double SDLCALL SDL_pow(double x, double y); -extern DECLSPEC float SDLCALL SDL_powf(float x, float y); -extern DECLSPEC double SDLCALL SDL_round(double x); -extern DECLSPEC float SDLCALL SDL_roundf(float x); -extern DECLSPEC long SDLCALL SDL_lround(double x); -extern DECLSPEC long SDLCALL SDL_lroundf(float x); -extern DECLSPEC double SDLCALL SDL_scalbn(double x, int n); -extern DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); -extern DECLSPEC double SDLCALL SDL_sin(double x); -extern DECLSPEC float SDLCALL SDL_sinf(float x); -extern DECLSPEC double SDLCALL SDL_sqrt(double x); -extern DECLSPEC float SDLCALL SDL_sqrtf(float x); -extern DECLSPEC double SDLCALL SDL_tan(double x); -extern DECLSPEC float SDLCALL SDL_tanf(float x); - -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - -/* SDL_iconv_* are now always real symbols/types, not macros or inlined. */ -typedef struct _SDL_iconv_t *SDL_iconv_t; -extern DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, - const char *fromcode); -extern DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); -extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, - size_t * inbytesleft, char **outbuf, - size_t * outbytesleft); - -/** - * This function converts a buffer or string between encodings in one pass, - * returning a string that must be freed with SDL_free() or NULL on error. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, - const char *fromcode, - const char *inbuf, - size_t inbytesleft); - -/* Some helper macros for common cases... */ -#define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) -#define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) -#define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) -#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) - -/* force builds using Clang's static analysis tools to use literal C runtime - here, since there are possibly tests that are ineffective otherwise. */ -#if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) - -/* The analyzer knows about strlcpy even when the system doesn't provide it */ -#ifndef HAVE_STRLCPY -size_t strlcpy(char* dst, const char* src, size_t size); -#endif - -/* The analyzer knows about strlcat even when the system doesn't provide it */ -#ifndef HAVE_STRLCAT -size_t strlcat(char* dst, const char* src, size_t size); -#endif - -#ifndef HAVE_WCSLCPY -size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); -#endif - -#ifndef HAVE_WCSLCAT -size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); -#endif - -#ifndef _WIN32 -/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ -/* not for windows: might conflict with string.h where strdup may have - * dllimport attribute: https://github.com/libsdl-org/SDL/issues/12948 */ -char *strdup(const char *str); -#endif - -/* Starting LLVM 16, the analyser errors out if these functions do not have - their prototype defined (clang-diagnostic-implicit-function-declaration) */ -#include -#include -#include - -#define SDL_malloc malloc -#define SDL_calloc calloc -#define SDL_realloc realloc -#define SDL_free free -#define SDL_memset memset -#define SDL_memcpy memcpy -#define SDL_memmove memmove -#define SDL_memcmp memcmp -#define SDL_strlcpy strlcpy -#define SDL_strlcat strlcat -#define SDL_strlen strlen -#define SDL_wcslen wcslen -#define SDL_wcslcpy wcslcpy -#define SDL_wcslcat wcslcat -#define SDL_strdup strdup -#define SDL_wcsdup wcsdup -#define SDL_strchr strchr -#define SDL_strrchr strrchr -#define SDL_strstr strstr -#define SDL_wcsstr wcsstr -#define SDL_strtokr strtok_r -#define SDL_strcmp strcmp -#define SDL_wcscmp wcscmp -#define SDL_strncmp strncmp -#define SDL_wcsncmp wcsncmp -#define SDL_strcasecmp strcasecmp -#define SDL_strncasecmp strncasecmp -#define SDL_sscanf sscanf -#define SDL_vsscanf vsscanf -#define SDL_snprintf snprintf -#define SDL_vsnprintf vsnprintf -#endif - -SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_BYTECAP(dwords*4) const void *src, size_t dwords) -{ - return SDL_memcpy(dst, src, dwords * 4); -} - -/** - * If a * b would overflow, return -1. - * - * Otherwise store a * b via ret and return 0. - * - * \since This function is available since SDL 2.24.0. - */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) -{ - if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; - } - *ret = a * b; - return 0; -} - -#if _SDL_HAS_BUILTIN(__builtin_mul_overflow) -/* This needs to be wrapped in an inline rather than being a direct #define, - * because __builtin_mul_overflow() is type-generic, but we want to be - * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) -{ - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; -} -#define SDL_size_mul_overflow(a, b, ret) (_SDL_size_mul_overflow_builtin(a, b, ret)) -#endif - -/** - * If a + b would overflow, return -1. - * - * Otherwise store a + b via ret and return 0. - * - * \since This function is available since SDL 2.24.0. - */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) -{ - if (b > SDL_SIZE_MAX - a) { - return -1; - } - *ret = a + b; - return 0; -} - -#if _SDL_HAS_BUILTIN(__builtin_add_overflow) -/* This needs to be wrapped in an inline rather than being a direct #define, - * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int _SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) -{ - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; -} -#define SDL_size_add_overflow(a, b, ret) (_SDL_size_add_overflow_builtin(a, b, ret)) -#endif - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_stdinc_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_surface.h b/code/thirdparty/SDL2-2.32.8/include/SDL_surface.h deleted file mode 100644 index 42ea5919af..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_surface.h +++ /dev/null @@ -1,1001 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategorySurface - * - * Header file for SDL_Surface definition and management functions. - */ - -#ifndef SDL_surface_h_ -#define SDL_surface_h_ - -#include "SDL_stdinc.h" -#include "SDL_pixels.h" -#include "SDL_rect.h" -#include "SDL_blendmode.h" -#include "SDL_rwops.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \name Surface flags - * - * These are the currently supported flags for the SDL_Surface. - * - * \internal - * Used internally (read-only). - */ -/* @{ */ -#define SDL_SWSURFACE 0 /**< Just here for compatibility */ -#define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */ -#define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */ -#define SDL_DONTFREE 0x00000004 /**< Surface is referenced internally */ -#define SDL_SIMD_ALIGNED 0x00000008 /**< Surface uses aligned memory */ -/* @} *//* Surface flags */ - -/** - * Evaluates to true if the surface needs to be locked before access. - */ -#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) - -typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ - -/** - * A collection of pixels used in software blitting. - * - * This structure should be treated as read-only, except for `pixels`, which, - * if not NULL, contains the raw pixel data for the surface. - */ -typedef struct SDL_Surface -{ - Uint32 flags; /**< Read-only */ - SDL_PixelFormat *format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-write */ - - /** Application data associated with the surface */ - void *userdata; /**< Read-write */ - - /** information needed for surfaces requiring locks */ - int locked; /**< Read-only */ - - /** list of BlitMap that hold a reference to this surface */ - void *list_blitmap; /**< Private */ - - /** clipping information */ - SDL_Rect clip_rect; /**< Read-only */ - - /** info for fast blit mapping to other surfaces */ - SDL_BlitMap *map; /**< Private */ - - /** Reference count -- used when freeing surface */ - int refcount; /**< Read-mostly */ -} SDL_Surface; - -/** - * The type of function used for surface blitting functions. - */ -typedef int (SDLCALL *SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, - struct SDL_Surface * dst, SDL_Rect * dstrect); - -/** - * The formula used for converting between YUV and RGB - */ -typedef enum SDL_YUV_CONVERSION_MODE -{ - SDL_YUV_CONVERSION_JPEG, /**< Full range JPEG */ - SDL_YUV_CONVERSION_BT601, /**< BT.601 (the default) */ - SDL_YUV_CONVERSION_BT709, /**< BT.709 */ - SDL_YUV_CONVERSION_AUTOMATIC /**< BT.601 for SD content, BT.709 for HD content */ -} SDL_YUV_CONVERSION_MODE; - -/** - * Allocate a new RGB surface. - * - * If `depth` is 4 or 8 bits, an empty palette is allocated for the surface. - * If `depth` is greater than 8 bits, the pixel format is set using the - * [RGBA]mask parameters. - * - * The [RGBA]mask parameters are the bitmasks used to extract that color from - * a pixel. For instance, `Rmask` being 0xFF000000 means the red data is - * stored in the most significant byte. Using zeros for the RGB masks sets a - * default value, based on the depth. For example: - * - * ```c++ - * SDL_CreateRGBSurface(0,w,h,32,0,0,0,0); - * ``` - * - * However, using zero for the Amask results in an Amask of 0. - * - * By default surfaces with an alpha mask are set up for blending as with: - * - * ```c++ - * SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND) - * ``` - * - * You can change this by calling SDL_SetSurfaceBlendMode() and selecting a - * different `blendMode`. - * - * \param flags the flags are unused and should be set to 0. - * \param width the width of the surface. - * \param height the height of the surface. - * \param depth the depth of the surface in bits. - * \param Rmask the red mask for the pixels. - * \param Gmask the green mask for the pixels. - * \param Bmask the blue mask for the pixels. - * \param Amask the alpha mask for the pixels. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRGBSurfaceFrom - * \sa SDL_CreateRGBSurfaceWithFormat - * \sa SDL_FreeSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface - (Uint32 flags, int width, int height, int depth, - Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); - - -/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */ - -/** - * Allocate a new RGB surface with a specific pixel format. - * - * This function operates mostly like SDL_CreateRGBSurface(), except instead - * of providing pixel color masks, you provide it with a predefined format - * from SDL_PixelFormatEnum. - * - * \param flags the flags are unused and should be set to 0. - * \param width the width of the surface. - * \param height the height of the surface. - * \param depth the depth of the surface in bits. - * \param format the SDL_PixelFormatEnum for the new surface's pixel format. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_CreateRGBSurface - * \sa SDL_CreateRGBSurfaceFrom - * \sa SDL_FreeSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat - (Uint32 flags, int width, int height, int depth, Uint32 format); - -/** - * Allocate a new RGB surface with existing pixel data. - * - * This function operates mostly like SDL_CreateRGBSurface(), except it does - * not allocate memory for the pixel data, instead the caller provides an - * existing buffer of data for the surface to use. - * - * No copy is made of the pixel data. Pixel data is not managed automatically; - * you must free the surface before you free the pixel data. - * - * \param pixels a pointer to existing pixel data. - * \param width the width of the surface. - * \param height the height of the surface. - * \param depth the depth of the surface in bits. - * \param pitch the pitch of the surface in bytes. - * \param Rmask the red mask for the pixels. - * \param Gmask the green mask for the pixels. - * \param Bmask the blue mask for the pixels. - * \param Amask the alpha mask for the pixels. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRGBSurface - * \sa SDL_CreateRGBSurfaceWithFormat - * \sa SDL_CreateRGBSurfaceWithFormatFrom - * \sa SDL_FreeSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, - int width, - int height, - int depth, - int pitch, - Uint32 Rmask, - Uint32 Gmask, - Uint32 Bmask, - Uint32 Amask); - -/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */ - -/** - * Allocate a new RGB surface with with a specific pixel format and existing - * pixel data. - * - * This function operates mostly like SDL_CreateRGBSurfaceFrom(), except - * instead of providing pixel color masks, you provide it with a predefined - * format from SDL_PixelFormatEnum. - * - * No copy is made of the pixel data. Pixel data is not managed automatically; - * you must free the surface before you free the pixel data. - * - * \param pixels a pointer to existing pixel data. - * \param width the width of the surface. - * \param height the height of the surface. - * \param depth the depth of the surface in bits. - * \param pitch the pitch of the surface in bytes. - * \param format the SDL_PixelFormatEnum for the new surface's pixel format. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_CreateRGBSurfaceFrom - * \sa SDL_CreateRGBSurfaceWithFormat - * \sa SDL_FreeSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom - (void *pixels, int width, int height, int depth, int pitch, Uint32 format); - -/** - * Free an RGB surface. - * - * It is safe to pass NULL to this function. - * - * \param surface the SDL_Surface to free. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateRGBSurface - * \sa SDL_CreateRGBSurfaceFrom - * \sa SDL_LoadBMP - * \sa SDL_LoadBMP_RW - */ -extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); - -/** - * Set the palette used by a surface. - * - * A single palette can be shared with many surfaces. - * - * \param surface the SDL_Surface structure to update. - * \param palette the SDL_Palette structure to use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, - SDL_Palette * palette); - -/** - * Set up a surface for directly accessing the pixels. - * - * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to - * and read from `surface->pixels`, using the pixel format stored in - * `surface->format`. Once you are done accessing the surface, you should use - * SDL_UnlockSurface() to release it. - * - * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to - * 0, then you can read and write to the surface at any time, and the pixel - * format of the surface will not change. - * - * \param surface the SDL_Surface structure to be locked. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MUSTLOCK - * \sa SDL_UnlockSurface - */ -extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); - -/** - * Release a surface after directly accessing the pixels. - * - * \param surface the SDL_Surface structure to be unlocked. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LockSurface - */ -extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); - -/** - * Load a BMP image from a seekable SDL data stream. - * - * The new surface should be freed with SDL_FreeSurface(). Not doing so will - * result in a memory leak. - * - * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile. - * Alternatively, you might also use the macro SDL_LoadBMP to load a bitmap - * from a file, convert it to an SDL_Surface and then close the file. - * - * \param src the data stream for the surface. - * \param freesrc non-zero to close the stream after being read. - * \returns a pointer to a new SDL_Surface structure or NULL if there was an - * error; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FreeSurface - * \sa SDL_RWFromFile - * \sa SDL_LoadBMP - * \sa SDL_SaveBMP_RW - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, - int freesrc); - -/** - * Load a surface from a file. - * - * Convenience macro. - */ -#define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) - -/** - * Save a surface to a seekable SDL data stream in BMP format. - * - * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the - * BMP directly. Other RGB formats with 8-bit or higher get converted to a - * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit - * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are - * not supported. - * - * \param surface the SDL_Surface structure containing the image to be saved. - * \param dst a data stream to save to. - * \param freedst non-zero to close the stream after being written. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_LoadBMP_RW - * \sa SDL_SaveBMP - */ -extern DECLSPEC int SDLCALL SDL_SaveBMP_RW - (SDL_Surface * surface, SDL_RWops * dst, int freedst); - -/** - * Save a surface to a file. - * - * Convenience macro. - */ -#define SDL_SaveBMP(surface, file) \ - SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) - -/** - * Set the RLE acceleration hint for a surface. - * - * If RLE is enabled, color key and alpha blending blits are much faster, but - * the surface must be locked before directly accessing the pixels. - * - * \param surface the SDL_Surface structure to optimize. - * \param flag 0 to disable, non-zero to enable RLE acceleration. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - * \sa SDL_LockSurface - * \sa SDL_UnlockSurface - */ -extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, - int flag); - -/** - * Returns whether the surface is RLE enabled - * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. - * - * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_SetSurfaceRLE - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface); - -/** - * Set the color key (transparent pixel) in a surface. - * - * The color key defines a pixel value that will be treated as transparent in - * a blit. For example, one can use this to specify that cyan pixels should be - * considered transparent, and therefore not rendered. - * - * It is a pixel of the format used by the surface, as generated by - * SDL_MapRGB(). - * - * RLE acceleration can substantially speed up blitting of images with large - * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details. - * - * \param surface the SDL_Surface structure to update. - * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key. - * \param key the transparent pixel. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - * \sa SDL_GetColorKey - */ -extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, - int flag, Uint32 key); - -/** - * Returns whether the surface has a color key - * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. - * - * \param surface the SDL_Surface structure to query. - * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_SetColorKey - * \sa SDL_GetColorKey - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface); - -/** - * Get the color key (transparent pixel) for a surface. - * - * The color key is a pixel of the format used by the surface, as generated by - * SDL_MapRGB(). - * - * If the surface doesn't have color key enabled this function returns -1. - * - * \param surface the SDL_Surface structure to query. - * \param key a pointer filled in with the transparent pixel. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - * \sa SDL_SetColorKey - */ -extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, - Uint32 * key); - -/** - * Set an additional color value multiplied into blit operations. - * - * When this surface is blitted, during the blit operation each source color - * channel is modulated by the appropriate color value according to the - * following formula: - * - * `srcC = srcC * (color / 255)` - * - * \param surface the SDL_Surface structure to update. - * \param r the red color value multiplied into blit operations. - * \param g the green color value multiplied into blit operations. - * \param b the blue color value multiplied into blit operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetSurfaceColorMod - * \sa SDL_SetSurfaceAlphaMod - */ -extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, - Uint8 r, Uint8 g, Uint8 b); - - -/** - * Get the additional color value multiplied into blit operations. - * - * \param surface the SDL_Surface structure to query. - * \param r a pointer filled in with the current red color value. - * \param g a pointer filled in with the current green color value. - * \param b a pointer filled in with the current blue color value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetSurfaceAlphaMod - * \sa SDL_SetSurfaceColorMod - */ -extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, - Uint8 * r, Uint8 * g, - Uint8 * b); - -/** - * Set an additional alpha value used in blit operations. - * - * When this surface is blitted, during the blit operation the source alpha - * value is modulated by this alpha value according to the following formula: - * - * `srcA = srcA * (alpha / 255)` - * - * \param surface the SDL_Surface structure to update. - * \param alpha the alpha value multiplied into blit operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetSurfaceAlphaMod - * \sa SDL_SetSurfaceColorMod - */ -extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, - Uint8 alpha); - -/** - * Get the additional alpha value used in blit operations. - * - * \param surface the SDL_Surface structure to query. - * \param alpha a pointer filled in with the current alpha value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetSurfaceColorMod - * \sa SDL_SetSurfaceAlphaMod - */ -extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, - Uint8 * alpha); - -/** - * Set the blend mode used for blit operations. - * - * To copy a surface to another surface (or texture) without blending with the - * existing data, the blendmode of the SOURCE surface should be set to - * `SDL_BLENDMODE_NONE`. - * - * \param surface the SDL_Surface structure to update. - * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetSurfaceBlendMode - */ -extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, - SDL_BlendMode blendMode); - -/** - * Get the blend mode used for blit operations. - * - * \param surface the SDL_Surface structure to query. - * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetSurfaceBlendMode - */ -extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, - SDL_BlendMode *blendMode); - -/** - * Set the clipping rectangle for a surface. - * - * When `surface` is the destination of a blit, only the area within the clip - * rectangle is drawn into. - * - * Note that blits are automatically clipped to the edges of the source and - * destination surfaces. - * - * \param surface the SDL_Surface structure to be clipped. - * \param rect the SDL_Rect structure representing the clipping rectangle, or - * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - * \sa SDL_GetClipRect - */ -extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, - const SDL_Rect * rect); - -/** - * Get the clipping rectangle for a surface. - * - * When `surface` is the destination of a blit, only the area within the clip - * rectangle is drawn into. - * - * \param surface the SDL_Surface structure representing the surface to be - * clipped. - * \param rect an SDL_Rect structure filled in with the clipping rectangle for - * the surface. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - * \sa SDL_SetClipRect - */ -extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface, - SDL_Rect * rect); - -/* - * Creates a new surface identical to the existing surface. - * - * The returned surface should be freed with SDL_FreeSurface(). - * - * \param surface the surface to duplicate. - * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for - * more information. - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface); - -/** - * Copy an existing surface to a new surface of the specified format. - * - * This function is used to optimize images for faster *repeat* blitting. This - * is accomplished by converting the original and storing the result as a new - * surface. The new, optimized surface can then be used as the source for - * future blits, making them faster. - * - * \param src the existing SDL_Surface structure to convert. - * \param fmt the SDL_PixelFormat structure that the new surface is optimized - * for. - * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocFormat - * \sa SDL_ConvertSurfaceFormat - * \sa SDL_CreateRGBSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface - (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags); - -/** - * Copy an existing surface to a new surface of the specified format enum. - * - * This function operates just like SDL_ConvertSurface(), but accepts an - * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such, - * it might be easier to call but it doesn't have access to palette - * information for the destination surface, in case that would be important. - * - * \param src the existing SDL_Surface structure to convert. - * \param pixel_format the SDL_PixelFormatEnum that the new surface is - * optimized for. - * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API. - * \returns the new SDL_Surface structure that is created or NULL if it fails; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AllocFormat - * \sa SDL_ConvertSurface - * \sa SDL_CreateRGBSurface - */ -extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat - (SDL_Surface * src, Uint32 pixel_format, Uint32 flags); - -/** - * Copy a block of pixels of one format to another format. - * - * \param width the width of the block to copy, in pixels. - * \param height the height of the block to copy, in pixels. - * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format. - * \param src a pointer to the source pixels. - * \param src_pitch the pitch of the source pixels, in bytes. - * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format. - * \param dst a pointer to be filled in with new pixel data. - * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, - Uint32 src_format, - const void * src, int src_pitch, - Uint32 dst_format, - void * dst, int dst_pitch); - -/** - * Premultiply the alpha on a block of pixels. - * - * This is safe to use with src == dst, but not for other overlapping areas. - * - * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888. - * - * \param width the width of the block to convert, in pixels. - * \param height the height of the block to convert, in pixels. - * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format. - * \param src a pointer to the source pixels. - * \param src_pitch the pitch of the source pixels, in bytes. - * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format. - * \param dst a pointer to be filled in with premultiplied pixel data. - * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, - Uint32 src_format, - const void * src, int src_pitch, - Uint32 dst_format, - void * dst, int dst_pitch); - -/** - * Perform a fast fill of a rectangle with a specific color. - * - * `color` should be a pixel of the format used by the surface, and can be - * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an - * alpha component then the destination is simply filled with that alpha - * information, no blending takes place. - * - * If there is a clip rectangle set on the destination (set via - * SDL_SetClipRect()), then this function will fill based on the intersection - * of the clip rectangle and `rect`. - * - * \param dst the SDL_Surface structure that is the drawing target. - * \param rect the SDL_Rect structure representing the rectangle to fill, or - * NULL to fill the entire surface. - * \param color the color to fill with. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FillRects - */ -extern DECLSPEC int SDLCALL SDL_FillRect - (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color); - -/** - * Perform a fast fill of a set of rectangles with a specific color. - * - * `color` should be a pixel of the format used by the surface, and can be - * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an - * alpha component then the destination is simply filled with that alpha - * information, no blending takes place. - * - * If there is a clip rectangle set on the destination (set via - * SDL_SetClipRect()), then this function will fill based on the intersection - * of the clip rectangle and `rect`. - * - * \param dst the SDL_Surface structure that is the drawing target. - * \param rects an array of SDL_Rect representing the rectangles to fill. - * \param count the number of rectangles in the array. - * \param color the color to fill with. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_FillRect - */ -extern DECLSPEC int SDLCALL SDL_FillRects - (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color); - -/* !!! FIXME: merge this documentation with the wiki */ - -/** - * Performs a fast blit from the source surface to the destination surface. - * - * This assumes that the source and destination rectangles are the same size. - * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangle is saved in `dstrect` after - * all clipping is performed. - * - * The blit function should not be called on a locked surface. - * - * The blit semantics for surfaces with and without blending and colorkey are - * defined as follows: - * - * ``` - * RGBA->RGB: - * Source surface blend mode set to SDL_BLENDMODE_BLEND: - * alpha-blend (using the source alpha-channel and per-surface alpha) - * SDL_SRCCOLORKEY ignored. - * Source surface blend mode set to SDL_BLENDMODE_NONE: - * copy RGB. - * if SDL_SRCCOLORKEY set, only copy the pixels matching the - * RGB values of the source color key, ignoring alpha in the - * comparison. - * - * RGB->RGBA: - * Source surface blend mode set to SDL_BLENDMODE_BLEND: - * alpha-blend (using the source per-surface alpha) - * Source surface blend mode set to SDL_BLENDMODE_NONE: - * copy RGB, set destination alpha to source per-surface alpha value. - * both: - * if SDL_SRCCOLORKEY set, only copy the pixels matching the - * source color key. - * - * RGBA->RGBA: - * Source surface blend mode set to SDL_BLENDMODE_BLEND: - * alpha-blend (using the source alpha-channel and per-surface alpha) - * SDL_SRCCOLORKEY ignored. - * Source surface blend mode set to SDL_BLENDMODE_NONE: - * copy all of RGBA to the destination. - * if SDL_SRCCOLORKEY set, only copy the pixels matching the - * RGB values of the source color key, ignoring alpha in the - * comparison. - * - * RGB->RGB: - * Source surface blend mode set to SDL_BLENDMODE_BLEND: - * alpha-blend (using the source per-surface alpha) - * Source surface blend mode set to SDL_BLENDMODE_NONE: - * copy RGB. - * both: - * if SDL_SRCCOLORKEY set, only copy the pixels matching the - * source color key. - * ``` - * - * You should call SDL_BlitSurface() unless you know exactly how SDL blitting - * works internally and how to use the other blit functions. - * - * \returns 0 if the blit is successful, otherwise it returns -1. - */ -#define SDL_BlitSurface SDL_UpperBlit - -/** - * Perform a fast blit from the source surface to the destination surface. - * - * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a - * macro for this function with a less confusing name. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - */ -extern DECLSPEC int SDLCALL SDL_UpperBlit - (SDL_Surface * src, const SDL_Rect * srcrect, - SDL_Surface * dst, SDL_Rect * dstrect); - -/** - * Perform low-level surface blitting only. - * - * This is a semi-private blit function and it performs low-level surface - * blitting, assuming the input rectangles have already been clipped. - * - * Unless you know what you're doing, you should be using SDL_BlitSurface() - * instead. - * - * \param src the SDL_Surface structure to be copied from. - * \param srcrect the SDL_Rect structure representing the rectangle to be - * copied, or NULL to copy the entire surface. - * \param dst the SDL_Surface structure that is the blit target. - * \param dstrect the SDL_Rect structure representing the rectangle that is - * copied into. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitSurface - */ -extern DECLSPEC int SDLCALL SDL_LowerBlit - (SDL_Surface * src, SDL_Rect * srcrect, - SDL_Surface * dst, SDL_Rect * dstrect); - - -/** - * Perform a fast, low quality, stretch blit between two surfaces of the same - * format. - * - * Please use SDL_BlitScaled() instead. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src, - const SDL_Rect * srcrect, - SDL_Surface * dst, - const SDL_Rect * dstrect); - -/** - * Perform bilinear scaling between two surfaces of the same format, 32BPP. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src, - const SDL_Rect * srcrect, - SDL_Surface * dst, - const SDL_Rect * dstrect); - - -/** - * Perform a scaled surface copy to a destination surface. - * - * SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is - * merely a macro for this function with a less confusing name. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitScaled - */ -extern DECLSPEC int SDLCALL SDL_UpperBlitScaled - (SDL_Surface * src, const SDL_Rect * srcrect, - SDL_Surface * dst, SDL_Rect * dstrect); - -#define SDL_BlitScaled SDL_UpperBlitScaled - - -/** - * Perform low-level surface scaled blitting only. - * - * This is a semi-private function and it performs low-level surface blitting, - * assuming the input rectangles have already been clipped. - * - * \param src the SDL_Surface structure to be copied from. - * \param srcrect the SDL_Rect structure representing the rectangle to be - * copied. - * \param dst the SDL_Surface structure that is the blit target. - * \param dstrect the SDL_Rect structure representing the rectangle that is - * copied into. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_BlitScaled - */ -extern DECLSPEC int SDLCALL SDL_LowerBlitScaled - (SDL_Surface * src, SDL_Rect * srcrect, - SDL_Surface * dst, SDL_Rect * dstrect); - -/** - * Set the YUV conversion mode - * - * \since This function is available since SDL 2.0.8. - */ -extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode); - -/** - * Get the YUV conversion mode - * - * \since This function is available since SDL 2.0.8. - */ -extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void); - -/** - * Get the YUV conversion mode, returning the correct mode for the resolution - * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC - * - * \since This function is available since SDL 2.0.8. - */ -extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_surface_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_system.h b/code/thirdparty/SDL2-2.32.8/include/SDL_system.h deleted file mode 100644 index 2f7a236f17..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_system.h +++ /dev/null @@ -1,642 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategorySystem - * - * Include file for platform specific SDL API functions - */ - -#ifndef SDL_system_h_ -#define SDL_system_h_ - -#include "SDL_stdinc.h" -#include "SDL_keyboard.h" -#include "SDL_render.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - - -/* Platform specific functions for Windows */ -#if defined(__WIN32__) || defined(__GDK__) - -typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam); - -/** - * Set a callback for every Windows message, run before TranslateMessage(). - * - * \param callback The SDL_WindowsMessageHook function to call. - * \param userdata a pointer to pass to every iteration of `callback`. - * - * \since This function is available since SDL 2.0.4. - */ -extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); - -#endif /* defined(__WIN32__) || defined(__GDK__) */ - -#if defined(__WIN32__) || defined(__WINGDK__) - -/** - * Get the D3D9 adapter index that matches the specified display index. - * - * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and - * controls on which monitor a full screen application will appear. - * - * \param displayIndex the display index for which to get the D3D9 adapter - * index. - * \returns the D3D9 adapter index on success or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.1. - */ -extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex ); - -typedef struct IDirect3DDevice9 IDirect3DDevice9; - -/** - * Get the D3D9 device associated with a renderer. - * - * Once you are done using the device, you should release it to avoid a - * resource leak. - * - * \param renderer the renderer from which to get the associated D3D device. - * \returns the D3D9 device associated with given renderer or NULL if it is - * not a D3D9 renderer; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.1. - */ -extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer); - -typedef struct ID3D11Device ID3D11Device; - -/** - * Get the D3D11 device associated with a renderer. - * - * Once you are done using the device, you should release it to avoid a - * resource leak. - * - * \param renderer the renderer from which to get the associated D3D11 device. - * \returns the D3D11 device associated with given renderer or NULL if it is - * not a D3D11 renderer; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer); - -#endif /* defined(__WIN32__) || defined(__WINGDK__) */ - -#if defined(__WIN32__) || defined(__GDK__) - -typedef struct ID3D12Device ID3D12Device; - -/** - * Get the D3D12 device associated with a renderer. - * - * Once you are done using the device, you should release it to avoid a - * resource leak. - * - * \param renderer the renderer from which to get the associated D3D12 device. - * \returns the D3D12 device associated with given renderer or NULL if it is - * not a D3D12 renderer; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* renderer); - -#endif /* defined(__WIN32__) || defined(__GDK__) */ - -#if defined(__WIN32__) || defined(__WINGDK__) - -/** - * Get the DXGI Adapter and Output indices for the specified display index. - * - * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and - * `EnumOutputs` respectively to get the objects required to create a DX10 or - * DX11 device and swap chain. - * - * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it - * returns an SDL_bool. - * - * \param displayIndex the display index for which to get both indices. - * \param adapterIndex a pointer to be filled in with the adapter index. - * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.2. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex ); - -#endif /* defined(__WIN32__) || defined(__WINGDK__) */ - -/* Platform specific functions for Linux */ -#ifdef __LINUX__ - -/** - * Sets the UNIX nice value for a thread. - * - * This uses setpriority() if possible, and RealtimeKit if available. - * - * \param threadID the Unix thread ID to change priority of. - * \param priority The new, Unix-specific, priority value. - * \returns 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority); - -/** - * Sets the priority (not nice level) and scheduling policy for a thread. - * - * This uses setpriority() if possible, and RealtimeKit if available. - * - * \param threadID The Unix thread ID to change priority of. - * \param sdlPriority The new SDL_ThreadPriority value. - * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR, - * SCHED_OTHER, etc...). - * \returns 0 on success, or -1 on error. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); - -#endif /* __LINUX__ */ - -/* Platform specific functions for iOS */ -#ifdef __IPHONEOS__ - -typedef void (SDLCALL *SDL_iOSAnimationCallback)(void*); - -/** - * Use this function to set the animation callback on Apple iOS. - * - * The function prototype for `callback` is: - * - * ```c - * void callback(void* callbackParam); - * ``` - * - * Where its parameter, `callbackParam`, is what was passed as `callbackParam` - * to SDL_iPhoneSetAnimationCallback(). - * - * This function is only available on Apple iOS. - * - * For more information see: - * https://github.com/libsdl-org/SDL/blob/main/docs/README-ios.md - * - * This functions is also accessible using the macro - * SDL_iOSSetAnimationCallback() since SDL 2.0.4. - * - * \param window the window for which the animation callback should be set. - * \param interval the number of frames after which **callback** will be - * called. - * \param callback the function to call for every frame. - * \param callbackParam a pointer that is passed to `callback`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_iPhoneSetEventPump - */ -extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); - -#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam) - - -/** - * Use this function to enable or disable the SDL event pump on Apple iOS. - * - * This function is only available on Apple iOS. - * - * This functions is also accessible using the macro SDL_iOSSetEventPump() - * since SDL 2.0.4. - * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_iPhoneSetAnimationCallback - */ -extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled); - -#define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled) - -/* end of iOS-specific functions. */ -#endif /* __IPHONEOS__ */ - - -/* Platform specific functions for Android */ -#ifdef __ANDROID__ - -/** - * Get the Android Java Native Interface Environment of the current thread. - * - * This is the JNIEnv one needs to access the Java virtual machine from native - * code, and is needed for many Android APIs to be usable from C. - * - * The prototype of the function in SDL's code actually declare a void* return - * type, even if the implementation returns a pointer to a JNIEnv. The - * rationale being that the SDL headers can avoid including jni.h. - * - * \returns a pointer to Java native interface object (JNIEnv) to which the - * current thread is attached, or 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AndroidGetActivity - */ -extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void); - -/** - * Retrieve the Java instance of the Android activity class. - * - * The prototype of the function in SDL's code actually declares a void* - * return type, even if the implementation returns a jobject. The rationale - * being that the SDL headers can avoid including jni.h. - * - * The jobject returned by the function is a local reference and must be - * released by the caller. See the PushLocalFrame() and PopLocalFrame() or - * DeleteLocalRef() functions of the Java native interface: - * - * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html - * - * \returns the jobject representing the instance of the Activity class of the - * Android application, or NULL on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AndroidGetJNIEnv - */ -extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void); - -/** - * Query Android API level of the current device. - * - * - API level 31: Android 12 - * - API level 30: Android 11 - * - API level 29: Android 10 - * - API level 28: Android 9 - * - API level 27: Android 8.1 - * - API level 26: Android 8.0 - * - API level 25: Android 7.1 - * - API level 24: Android 7.0 - * - API level 23: Android 6.0 - * - API level 22: Android 5.1 - * - API level 21: Android 5.0 - * - API level 20: Android 4.4W - * - API level 19: Android 4.4 - * - API level 18: Android 4.3 - * - API level 17: Android 4.2 - * - API level 16: Android 4.1 - * - API level 15: Android 4.0.3 - * - API level 14: Android 4.0 - * - API level 13: Android 3.2 - * - API level 12: Android 3.1 - * - API level 11: Android 3.0 - * - API level 10: Android 2.3.3 - * - * \returns the Android API level. - * - * \since This function is available since SDL 2.0.12. - */ -extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); - -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.8. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - -/** - * Query if the application is running on a Chromebook. - * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); - -/** - * Query if the application is running on a Samsung DeX docking station. - * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); - -/** - * Trigger the Android system back button behavior. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); - -/** - * See the official Android developer guide for more information: - * http://developer.android.com/guide/topics/data/data-storage.html - */ -#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 -#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 - -/** - * Get the path used for internal storage for this application. - * - * This path is unique to your application and cannot be written to by other - * applications. - * - * Your internal storage path is typically: - * `/data/data/your.app.package/files`. - * - * \returns the path used for internal storage or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AndroidGetExternalStorageState - */ -extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void); - -/** - * Get the current state of external storage. - * - * The current state of external storage, a bitmask of these values: - * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`. - * - * If external storage is currently unavailable, this will return 0. - * - * \returns the current state of external storage on success or 0 on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AndroidGetExternalStoragePath - */ -extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void); - -/** - * Get the path used for external storage for this application. - * - * This path is unique to your application, but is public and can be written - * to by other applications. - * - * Your external storage path is typically: - * `/storage/sdcard0/Android/data/your.app.package/files`. - * - * \returns the path used for external storage for this application on success - * or NULL on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AndroidGetExternalStorageState - */ -extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void); - -/** - * Request permissions at runtime. - * - * This blocks the calling thread until the permission is granted or denied. - * - * \param permission The permission to request. - * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission); - -/** - * Shows an Android toast notification. - * - * Toasts are a sort of lightweight notification that are unique to Android. - * - * https://developer.android.com/guide/topics/ui/notifiers/toasts - * - * Shows toast in UI thread. - * - * For the `gravity` parameter, choose a value from here, or -1 if you don't - * have a preference: - * - * https://developer.android.com/reference/android/view/Gravity - * - * \param message text message to be shown. - * \param duration 0=short, 1=long. - * \param gravity where the notification should appear on the screen. - * \param xoffset set this parameter only when gravity >=0. - * \param yoffset set this parameter only when gravity >=0. - * \returns 0 if success, -1 if any error occurs. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset); - -/** - * Send a user command to SDLActivity. - * - * Override "boolean onUnhandledMessage(Message msg)" to handle the message. - * - * \param command user command that must be greater or equal to 0x8000. - * \param param user parameter. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param); - -#endif /* __ANDROID__ */ - -/* Platform specific functions for WinRT */ -#ifdef __WINRT__ - -/** - * WinRT / Windows Phone path types - */ -typedef enum SDL_WinRT_Path -{ - /** \brief The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** \brief The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** \brief The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** \brief The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** \brief Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** \brief Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** \brief Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** \brief XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.3. - * - * \sa SDL_WinRTGetFSPathUTF8 - */ -extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType); - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.3. - * - * \sa SDL_WinRTGetFSPathUNICODE - */ -extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 2.0.8. - */ -extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily(); - -#endif /* __WINRT__ */ - -/** - * Query if the current device is a tablet. - * - * If SDL can't determine this, it will return SDL_FALSE. - * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); - -/* Functions used by iOS application delegates to notify SDL about state changes */ -extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); -extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); -extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void); -extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); -extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); -extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void); -#ifdef __IPHONEOS__ -extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); -#endif - -/* Functions used only by GDK */ -#if defined(__GDK__) -typedef struct XTaskQueueObject *XTaskQueueHandle; -typedef struct XUser *XUserHandle; - -/** - * Gets a reference to the global async task queue handle for GDK, - * initializing if needed. - * - * Once you are done with the task queue, you should call - * XTaskQueueCloseHandle to reduce the reference count to avoid a resource - * leak. - * - * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns 0 if success, -1 if any error occurs. - * - * \since This function is available since SDL 2.24.0. - */ -extern DECLSPEC int SDLCALL SDL_GDKGetTaskQueue(XTaskQueueHandle * outTaskQueue); - -/** - * Gets a reference to the default user handle for GDK. - * - * This is effectively a synchronous version of XUserAddAsync, which always - * prefers the default user and allows a sign-in UI. - * - * \param outUserHandle a pointer to be filled in with the default user - * handle. - * \returns 0 if success, -1 if any error occurs. - * - * \since This function is available since SDL 2.28.0. - */ -extern DECLSPEC int SDLCALL SDL_GDKGetDefaultUser(XUserHandle * outUserHandle); - -#endif - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_system_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_syswm.h b/code/thirdparty/SDL2-2.32.8/include/SDL_syswm.h deleted file mode 100644 index 18f6873299..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_syswm.h +++ /dev/null @@ -1,386 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: SYSWM */ - -/* - * # CategorySYSWM - * - * Include file for SDL custom system window manager hooks. - * - * Your application has access to a special type of event SDL_SYSWMEVENT, - * which contains window-manager specific information and arrives whenever - * an unhandled window event occurs. This event is ignored by default, but - * you can enable it with SDL_EventState(). - */ - -#ifndef SDL_syswm_h_ -#define SDL_syswm_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_video.h" -#include "SDL_version.h" - -struct SDL_SysWMinfo; - -#if !defined(SDL_PROTOTYPES_ONLY) - -#if defined(SDL_VIDEO_DRIVER_WINDOWS) -#ifndef WIN32_LEAN_AND_MEAN -#define WIN32_LEAN_AND_MEAN -#endif -#ifndef NOMINMAX /* don't define min() and max(). */ -#define NOMINMAX -#endif -#include -#endif - -#if defined(SDL_VIDEO_DRIVER_WINRT) -#include -#endif - -/* This is the structure for custom window manager events */ -#if defined(SDL_VIDEO_DRIVER_X11) -#if defined(__APPLE__) && defined(__MACH__) -/* conflicts with Quickdraw.h */ -#define Cursor X11Cursor -#endif - -#include -#include - -#if defined(__APPLE__) && defined(__MACH__) -/* matches the re-define above */ -#undef Cursor -#endif - -#endif /* defined(SDL_VIDEO_DRIVER_X11) */ - -#if defined(SDL_VIDEO_DRIVER_DIRECTFB) -#include -#endif - -#if defined(SDL_VIDEO_DRIVER_COCOA) -#ifdef __OBJC__ -@class NSWindow; -#else -typedef struct _NSWindow NSWindow; -#endif -#endif - -#if defined(SDL_VIDEO_DRIVER_UIKIT) -#ifdef __OBJC__ -#include -#else -typedef struct _UIWindow UIWindow; -typedef struct _UIViewController UIViewController; -#endif -typedef Uint32 GLuint; -#endif - -#if defined(SDL_VIDEO_VULKAN) || defined(SDL_VIDEO_METAL) -#define SDL_METALVIEW_TAG 255 -#endif - -#if defined(SDL_VIDEO_DRIVER_ANDROID) -typedef struct ANativeWindow ANativeWindow; -typedef void *EGLSurface; -#endif - -#if defined(SDL_VIDEO_DRIVER_VIVANTE) -#include "SDL_egl.h" -#endif - -#if defined(SDL_VIDEO_DRIVER_OS2) -#define INCL_WIN -#include -#endif -#endif /* SDL_PROTOTYPES_ONLY */ - -#if defined(SDL_VIDEO_DRIVER_KMSDRM) -struct gbm_device; -#endif - - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -#if !defined(SDL_PROTOTYPES_ONLY) - -/** - * These are the various supported windowing subsystems - */ -typedef enum SDL_SYSWM_TYPE -{ - SDL_SYSWM_UNKNOWN, - SDL_SYSWM_WINDOWS, - SDL_SYSWM_X11, - SDL_SYSWM_DIRECTFB, - SDL_SYSWM_COCOA, - SDL_SYSWM_UIKIT, - SDL_SYSWM_WAYLAND, - SDL_SYSWM_MIR, /* no longer available, left for API/ABI compatibility. Remove in 2.1! */ - SDL_SYSWM_WINRT, - SDL_SYSWM_ANDROID, - SDL_SYSWM_VIVANTE, - SDL_SYSWM_OS2, - SDL_SYSWM_HAIKU, - SDL_SYSWM_KMSDRM, - SDL_SYSWM_RISCOS -} SDL_SYSWM_TYPE; - -/** - * The custom event structure. - */ -struct SDL_SysWMmsg -{ - SDL_version version; - SDL_SYSWM_TYPE subsystem; - union - { -#if defined(SDL_VIDEO_DRIVER_WINDOWS) - struct { - HWND hwnd; /**< The window for the message */ - UINT msg; /**< The type of message */ - WPARAM wParam; /**< WORD message parameter */ - LPARAM lParam; /**< LONG message parameter */ - } win; -#endif -#if defined(SDL_VIDEO_DRIVER_X11) - struct { - XEvent event; - } x11; -#endif -#if defined(SDL_VIDEO_DRIVER_DIRECTFB) - struct { - DFBEvent event; - } dfb; -#endif -#if defined(SDL_VIDEO_DRIVER_COCOA) - struct - { - /* Latest version of Xcode clang complains about empty structs in C v. C++: - error: empty struct has size 0 in C, size 1 in C++ - */ - int dummy; - /* No Cocoa window events yet */ - } cocoa; -#endif -#if defined(SDL_VIDEO_DRIVER_UIKIT) - struct - { - int dummy; - /* No UIKit window events yet */ - } uikit; -#endif -#if defined(SDL_VIDEO_DRIVER_VIVANTE) - struct - { - int dummy; - /* No Vivante window events yet */ - } vivante; -#endif -#if defined(SDL_VIDEO_DRIVER_OS2) - struct - { - BOOL fFrame; /**< TRUE if hwnd is a frame window */ - HWND hwnd; /**< The window receiving the message */ - ULONG msg; /**< The message identifier */ - MPARAM mp1; /**< The first first message parameter */ - MPARAM mp2; /**< The second first message parameter */ - } os2; -#endif - /* Can't have an empty union */ - int dummy; - } msg; -}; - -/** - * The custom window manager information structure. - * - * When this structure is returned, it holds information about which low level - * system it is using, and will be one of SDL_SYSWM_TYPE. - */ -struct SDL_SysWMinfo -{ - SDL_version version; - SDL_SYSWM_TYPE subsystem; - union - { -#if defined(SDL_VIDEO_DRIVER_WINDOWS) - struct - { - HWND window; /**< The window handle */ - HDC hdc; /**< The window device context */ - HINSTANCE hinstance; /**< The instance handle */ - } win; -#endif -#if defined(SDL_VIDEO_DRIVER_WINRT) - struct - { - IInspectable * window; /**< The WinRT CoreWindow */ - } winrt; -#endif -#if defined(SDL_VIDEO_DRIVER_X11) - struct - { - Display *display; /**< The X11 display */ - Window window; /**< The X11 window */ - } x11; -#endif -#if defined(SDL_VIDEO_DRIVER_DIRECTFB) - struct - { - IDirectFB *dfb; /**< The directfb main interface */ - IDirectFBWindow *window; /**< The directfb window handle */ - IDirectFBSurface *surface; /**< The directfb client surface */ - } dfb; -#endif -#if defined(SDL_VIDEO_DRIVER_COCOA) - struct - { -#if defined(__OBJC__) && defined(__has_feature) - #if __has_feature(objc_arc) - NSWindow __unsafe_unretained *window; /**< The Cocoa window */ - #else - NSWindow *window; /**< The Cocoa window */ - #endif -#else - NSWindow *window; /**< The Cocoa window */ -#endif - } cocoa; -#endif -#if defined(SDL_VIDEO_DRIVER_UIKIT) - struct - { -#if defined(__OBJC__) && defined(__has_feature) - #if __has_feature(objc_arc) - UIWindow __unsafe_unretained *window; /**< The UIKit window */ - #else - UIWindow *window; /**< The UIKit window */ - #endif -#else - UIWindow *window; /**< The UIKit window */ -#endif - GLuint framebuffer; /**< The GL view's Framebuffer Object. It must be bound when rendering to the screen using GL. */ - GLuint colorbuffer; /**< The GL view's color Renderbuffer Object. It must be bound when SDL_GL_SwapWindow is called. */ - GLuint resolveFramebuffer; /**< The Framebuffer Object which holds the resolve color Renderbuffer, when MSAA is used. */ - } uikit; -#endif -#if defined(SDL_VIDEO_DRIVER_WAYLAND) - struct - { - struct wl_display *display; /**< Wayland display */ - struct wl_surface *surface; /**< Wayland surface */ - void *shell_surface; /**< DEPRECATED Wayland shell_surface (window manager handle) */ - struct wl_egl_window *egl_window; /**< Wayland EGL window (native window) */ - struct xdg_surface *xdg_surface; /**< Wayland xdg surface (window manager handle) */ - struct xdg_toplevel *xdg_toplevel; /**< Wayland xdg toplevel role */ - struct xdg_popup *xdg_popup; /**< Wayland xdg popup role */ - struct xdg_positioner *xdg_positioner; /**< Wayland xdg positioner, for popup */ - } wl; -#endif -#if defined(SDL_VIDEO_DRIVER_MIR) /* no longer available, left for API/ABI compatibility. Remove in 2.1! */ - struct - { - void *connection; /**< Mir display server connection */ - void *surface; /**< Mir surface */ - } mir; -#endif - -#if defined(SDL_VIDEO_DRIVER_ANDROID) - struct - { - ANativeWindow *window; - EGLSurface surface; - } android; -#endif - -#if defined(SDL_VIDEO_DRIVER_OS2) - struct - { - HWND hwnd; /**< The window handle */ - HWND hwndFrame; /**< The frame window handle */ - } os2; -#endif - -#if defined(SDL_VIDEO_DRIVER_VIVANTE) - struct - { - EGLNativeDisplayType display; - EGLNativeWindowType window; - } vivante; -#endif - -#if defined(SDL_VIDEO_DRIVER_KMSDRM) - struct - { - int dev_index; /**< Device index (ex: the X in /dev/dri/cardX) */ - int drm_fd; /**< DRM FD (unavailable on Vulkan windows) */ - struct gbm_device *gbm_dev; /**< GBM device (unavailable on Vulkan windows) */ - } kmsdrm; -#endif - - /* Make sure this union is always 64 bytes (8 64-bit pointers). */ - /* Be careful not to overflow this if you add a new target! */ - Uint8 dummy[64]; - } info; -}; - -#endif /* SDL_PROTOTYPES_ONLY */ - -typedef struct SDL_SysWMinfo SDL_SysWMinfo; - - -/** - * Get driver-specific information about a window. - * - * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo. - * - * The caller must initialize the `info` structure's version by using - * `SDL_VERSION(&info.version)`, and then this function will fill in the rest - * of the structure with information about the given window. - * - * \param window the window about which information is being requested. - * \param info an SDL_SysWMinfo structure filled in with window information. - * \returns SDL_TRUE if the function is implemented and the `version` member - * of the `info` struct is valid, or SDL_FALSE if the information - * could not be retrieved; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window, - SDL_SysWMinfo * info); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_syswm_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_images.h b/code/thirdparty/SDL2-2.32.8/include/SDL_test_images.h deleted file mode 100644 index d593a31565..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_images.h +++ /dev/null @@ -1,78 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* - * \file SDL_test_images.h - * - * Include file for SDL test framework. - * - * This code is a part of the SDL2_test library, not the main SDL library. - */ - -/* - - Defines some images for tests. - -*/ - -#ifndef SDL_test_images_h_ -#define SDL_test_images_h_ - -#include "SDL.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* - *Type for test images. - */ -typedef struct SDLTest_SurfaceImage_s { - int width; - int height; - unsigned int bytes_per_pixel; /* 3:RGB, 4:RGBA */ - const char *pixel_data; -} SDLTest_SurfaceImage_t; - -/* Test images */ -SDL_Surface *SDLTest_ImageBlit(void); -SDL_Surface *SDLTest_ImageBlitColor(void); -SDL_Surface *SDLTest_ImageBlitAlpha(void); -SDL_Surface *SDLTest_ImageBlitBlendAdd(void); -SDL_Surface *SDLTest_ImageBlitBlend(void); -SDL_Surface *SDLTest_ImageBlitBlendMod(void); -SDL_Surface *SDLTest_ImageBlitBlendNone(void); -SDL_Surface *SDLTest_ImageBlitBlendAll(void); -SDL_Surface *SDLTest_ImageFace(void); -SDL_Surface *SDLTest_ImagePrimitives(void); -SDL_Surface *SDLTest_ImagePrimitivesBlend(void); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_test_images_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_random.h b/code/thirdparty/SDL2-2.32.8/include/SDL_test_random.h deleted file mode 100644 index 05d6d3ee5e..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_random.h +++ /dev/null @@ -1,115 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* - * \file SDL_test_random.h - * - * Include file for SDL test framework. - * - * This code is a part of the SDL2_test library, not the main SDL library. - */ - -/* - - A "32-bit Multiply with carry random number generator. Very fast. - Includes a list of recommended multipliers. - - multiply-with-carry generator: x(n) = a*x(n-1) + carry mod 2^32. - period: (a*2^31)-1 - -*/ - -#ifndef SDL_test_random_h_ -#define SDL_test_random_h_ - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* --- Definitions */ - -/* - * Macros that return a random number in a specific format. - */ -#define SDLTest_RandomInt(c) ((int)SDLTest_Random(c)) - -/* - * Context structure for the random number generator state. - */ - typedef struct { - unsigned int a; - unsigned int x; - unsigned int c; - unsigned int ah; - unsigned int al; - } SDLTest_RandomContext; - - -/* --- Function prototypes */ - -/* - * \brief Initialize random number generator with two integers. - * - * Note: The random sequence of numbers returned by ...Random() is the - * same for the same two integers and has a period of 2^31. - * - * \param rndContext pointer to context structure - * \param xi integer that defines the random sequence - * \param ci integer that defines the random sequence - * - */ - void SDLTest_RandomInit(SDLTest_RandomContext * rndContext, unsigned int xi, - unsigned int ci); - -/* - * \brief Initialize random number generator based on current system time. - * - * \param rndContext pointer to context structure - * - */ - void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext); - - -/* - * \brief Initialize random number generator based on current system time. - * - * Note: ...RandomInit() or ...RandomInitTime() must have been called - * before using this function. - * - * \param rndContext pointer to context structure - * - * \returns a random number (32bit unsigned integer) - * - */ - unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_test_random_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_thread.h b/code/thirdparty/SDL2-2.32.8/include/SDL_thread.h deleted file mode 100644 index ac405d85ed..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_thread.h +++ /dev/null @@ -1,468 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_thread_h_ -#define SDL_thread_h_ - -/** - * # CategoryThread - * - * Header for the SDL thread management routines. - */ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -/* Thread synchronization primitives */ -#include "SDL_atomic.h" -#include "SDL_mutex.h" - -#if (defined(__WIN32__) || defined(__GDK__)) && !defined(__WINRT__) -#include /* _beginthreadex() and _endthreadex() */ -#endif -#if defined(__OS2__) /* for _beginthread() and _endthread() */ -#ifndef __EMX__ -#include -#else -#include -#endif -#endif - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* The SDL thread structure, defined in SDL_thread.c */ -struct SDL_Thread; -typedef struct SDL_Thread SDL_Thread; - -/* The SDL thread ID */ -typedef unsigned long SDL_threadID; - -/* Thread local storage ID, 0 is the invalid ID */ -typedef unsigned int SDL_TLSID; - -/** - * The SDL thread priority. - * - * SDL will make system changes as necessary in order to apply the thread - * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. - * - * On many systems you require special privileges to set high or time critical - * priority. - */ -typedef enum SDL_ThreadPriority { - SDL_THREAD_PRIORITY_LOW, - SDL_THREAD_PRIORITY_NORMAL, - SDL_THREAD_PRIORITY_HIGH, - SDL_THREAD_PRIORITY_TIME_CRITICAL -} SDL_ThreadPriority; - -/** - * The function passed to SDL_CreateThread(). - * - * \param data what was passed as `data` to SDL_CreateThread(). - * \returns a value that can be reported through SDL_WaitThread(). - */ -typedef int (SDLCALL * SDL_ThreadFunction) (void *data); - - -#if (defined(__WIN32__) || defined(__GDK__)) && !defined(__WINRT__) -/** - * \file SDL_thread.h - * - * We compile SDL into a DLL. This means, that it's the DLL which - * creates a new thread for the calling process with the SDL_CreateThread() - * API. There is a problem with this, that only the RTL of the SDL2.DLL will - * be initialized for those threads, and not the RTL of the calling - * application! - * - * To solve this, we make a little hack here. - * - * We'll always use the caller's _beginthread() and _endthread() APIs to - * start a new thread. This way, if it's the SDL2.DLL which uses this API, - * then the RTL of SDL2.DLL will be used to create the new thread, and if it's - * the application, then the RTL of the application will be used. - * - * So, in short: - * Always use the _beginthread() and _endthread() of the calling runtime - * library! - */ -#define SDL_PASSED_BEGINTHREAD_ENDTHREAD - -typedef uintptr_t (__cdecl * pfnSDL_CurrentBeginThread) - (void *, unsigned, unsigned (__stdcall *func)(void *), - void * /*arg*/, unsigned, unsigned * /* threadID */); -typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code); - -#ifndef SDL_beginthread -#define SDL_beginthread _beginthreadex -#endif -#ifndef SDL_endthread -#define SDL_endthread _endthreadex -#endif - -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, - pfnSDL_CurrentBeginThread pfnBeginThread, - pfnSDL_CurrentEndThread pfnEndThread); - -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, - const char *name, const size_t stacksize, void *data, - pfnSDL_CurrentBeginThread pfnBeginThread, - pfnSDL_CurrentEndThread pfnEndThread); - - -#if defined(SDL_CreateThread) && SDL_DYNAMIC_API -#undef SDL_CreateThread -#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#undef SDL_CreateThreadWithStackSize -#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#else -#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#endif - -#elif defined(__OS2__) -/* - * just like the windows case above: We compile SDL2 - * into a dll with Watcom's runtime statically linked. - */ -#define SDL_PASSED_BEGINTHREAD_ENDTHREAD - -typedef int (*pfnSDL_CurrentBeginThread)(void (*func)(void *), void *, unsigned, void * /*arg*/); -typedef void (*pfnSDL_CurrentEndThread)(void); - -#ifndef SDL_beginthread -#define SDL_beginthread _beginthread -#endif -#ifndef SDL_endthread -#define SDL_endthread _endthread -#endif - -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, - pfnSDL_CurrentBeginThread pfnBeginThread, - pfnSDL_CurrentEndThread pfnEndThread); -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data, - pfnSDL_CurrentBeginThread pfnBeginThread, - pfnSDL_CurrentEndThread pfnEndThread); - -#if defined(SDL_CreateThread) && SDL_DYNAMIC_API -#undef SDL_CreateThread -#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#undef SDL_CreateThreadWithStackSize -#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#else -#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) -#endif - -#else - -/** - * Create a new thread with a default stack size. - * - * This is equivalent to calling: - * - * ```c - * SDL_CreateThreadWithStackSize(fn, name, 0, data); - * ``` - * - * \param fn the SDL_ThreadFunction function to call in the new thread. - * \param name the name of the thread. - * \param data a pointer that is passed to `fn`. - * \returns an opaque pointer to the new thread object on success, NULL if the - * new thread could not be created; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateThreadWithStackSize - * \sa SDL_WaitThread - */ -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); - -/** - * Create a new thread with a specific stack size. - * - * SDL makes an attempt to report `name` to the system, so that debuggers can - * display it. Not all platforms support this. - * - * Thread naming is a little complicated: Most systems have very small limits - * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual - * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to - * see what happens with your system's debugger. The name should be UTF-8 (but - * using the naming limits of C identifiers is a better bet). There are no - * requirements for thread naming conventions, so long as the string is - * null-terminated UTF-8, but these guidelines are helpful in choosing a name: - * - * https://stackoverflow.com/questions/149932/naming-conventions-for-threads - * - * If a system imposes requirements, SDL will try to munge the string for it - * (truncate, etc), but the original string contents will be available from - * SDL_GetThreadName(). - * - * The size (in bytes) of the new stack can be specified. Zero means "use the - * system default" which might be wildly different between platforms. x86 - * Linux generally defaults to eight megabytes, an embedded device might be a - * few kilobytes instead. You generally need to specify a stack that is a - * multiple of the system's page size (in many cases, this is 4 kilobytes, but - * check your system documentation). - * - * In SDL 2.1, stack size will be folded into the original SDL_CreateThread - * function, but for backwards compatibility, this is currently a separate - * function. - * - * \param fn the SDL_ThreadFunction function to call in the new thread. - * \param name the name of the thread. - * \param stacksize the size, in bytes, to allocate for the new thread stack. - * \param data a pointer that is passed to `fn`. - * \returns an opaque pointer to the new thread object on success, NULL if the - * new thread could not be created; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_WaitThread - */ -extern DECLSPEC SDL_Thread *SDLCALL -SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data); - -#endif - -/** - * Get the thread name as it was specified in SDL_CreateThread(). - * - * This is internal memory, not to be freed by the caller, and remains valid - * until the specified thread is cleaned up by SDL_WaitThread(). - * - * \param thread the thread to query. - * \returns a pointer to a UTF-8 string that names the specified thread, or - * NULL if it doesn't have a name. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateThread - */ -extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread); - -/** - * Get the thread identifier for the current thread. - * - * This thread identifier is as reported by the underlying operating system. - * If SDL is running on a platform that does not support threads the return - * value will always be zero. - * - * This function also returns a valid thread ID when called from the main - * thread. - * - * \returns the ID of the current thread. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetThreadID - */ -extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); - -/** - * Get the thread identifier for the specified thread. - * - * This thread identifier is as reported by the underlying operating system. - * If SDL is running on a platform that does not support threads the return - * value will always be zero. - * - * \param thread the thread to query. - * \returns the ID of the specified thread, or the ID of the current thread if - * `thread` is NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ThreadID - */ -extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); - -/** - * Set the priority for the current thread. - * - * Note that some platforms will not let you alter the priority (or at least, - * promote the thread to a higher priority) at all, and some require you to be - * an administrator account. Be prepared for this to fail. - * - * \param priority the SDL_ThreadPriority to set. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); - -/** - * Wait for a thread to finish. - * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. - * - * Once a thread has been cleaned up through this function, the SDL_Thread - * that references it becomes invalid and should not be referenced again. As - * such, only one thread may call SDL_WaitThread() on another. - * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. - * - * You may not wait on a thread that has been used in a call to - * SDL_DetachThread(). Use either that function or this one, but not both, or - * behavior is undefined. - * - * It is safe to pass a NULL thread to this function; it is a no-op. - * - * Note that the thread pointer is freed by this function and is not valid - * afterward. - * - * \param thread the SDL_Thread pointer that was returned from the - * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateThread - * \sa SDL_DetachThread - */ -extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); - -/** - * Let a thread clean up on exit without intervention. - * - * A thread may be "detached" to signify that it should not remain until - * another thread has called SDL_WaitThread() on it. Detaching a thread is - * useful for long-running threads that nothing needs to synchronize with or - * further manage. When a detached thread is done, it simply goes away. - * - * There is no way to recover the return code of a detached thread. If you - * need this, don't detach the thread and instead use SDL_WaitThread(). - * - * Once a thread is detached, you should usually assume the SDL_Thread isn't - * safe to reference again, as it will become invalid immediately upon the - * detached thread's exit, instead of remaining until someone has called - * SDL_WaitThread() to finally clean it up. As such, don't detach the same - * thread more than once. - * - * If a thread has already exited when passed to SDL_DetachThread(), it will - * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is - * not safe to detach a thread that might be used with SDL_WaitThread(). - * - * You may not call SDL_WaitThread() on a thread that has been detached. Use - * either that function or this one, but not both, or behavior is undefined. - * - * It is safe to pass NULL to this function; it is a no-op. - * - * \param thread the SDL_Thread pointer that was returned from the - * SDL_CreateThread() call that started this thread. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_CreateThread - * \sa SDL_WaitThread - */ -extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread); - -/** - * Create a piece of thread-local storage. - * - * This creates an identifier that is globally visible to all threads but - * refers to data that is thread-specific. - * - * \returns the newly created thread local storage identifier or 0 on error. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_TLSGet - * \sa SDL_TLSSet - */ -extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); - -/** - * Get the current thread's value associated with a thread local storage ID. - * - * \param id the thread local storage ID. - * \returns the value associated with the ID for the current thread or NULL if - * no value has been set; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_TLSCreate - * \sa SDL_TLSSet - */ -extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); - -typedef void (SDLCALL *SDL_TLSDestructorCallback)(void*); - -/** - * Set the current thread's value associated with a thread local storage ID. - * - * The function prototype for `destructor` is: - * - * ```c - * void destructor(void *value) - * ``` - * - * where its parameter `value` is what was passed as `value` to SDL_TLSSet(). - * - * \param id the thread local storage ID. - * \param value the value to associate with the ID for the current thread. - * \param destructor a function called when the thread exits, to free the - * value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_TLSCreate - * \sa SDL_TLSGet - */ -extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, SDL_TLSDestructorCallback destructor); - -/** - * Cleanup all TLS data for this thread. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC void SDLCALL SDL_TLSCleanup(void); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_thread_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_timer.h b/code/thirdparty/SDL2-2.32.8/include/SDL_timer.h deleted file mode 100644 index 60969690b2..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_timer.h +++ /dev/null @@ -1,222 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_timer_h_ -#define SDL_timer_h_ - -/** - * # CategoryTimer - * - * Header for the SDL time management routines. - */ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Get the number of milliseconds since SDL library initialization. - * - * This value wraps if the program runs for more than ~49 days. - * - * This function is not recommended as of SDL 2.0.18; use SDL_GetTicks64() - * instead, where the value doesn't wrap every ~49 days. There are places in - * SDL where we provide a 32-bit timestamp that can not change without - * breaking binary compatibility, though, so this function isn't officially - * deprecated. - * - * \returns an unsigned 32-bit value representing the number of milliseconds - * since the SDL library initialized. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_TICKS_PASSED - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); - -/** - * Get the number of milliseconds since SDL library initialization. - * - * Note that you should not use the SDL_TICKS_PASSED macro with values - * returned by this function, as that macro does clever math to compensate for - * the 32-bit overflow every ~49 days that SDL_GetTicks() suffers from. 64-bit - * values from this function can be safely compared directly. - * - * For example, if you want to wait 100 ms, you could do this: - * - * ```c - * const Uint64 timeout = SDL_GetTicks64() + 100; - * while (SDL_GetTicks64() < timeout) { - * // ... do work until timeout has elapsed - * } - * ``` - * - * \returns an unsigned 64-bit value representing the number of milliseconds - * since the SDL library initialized. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void); - -/** - * Compare 32-bit SDL ticks values, and return true if `A` has passed `B`. - * - * This should be used with results from SDL_GetTicks(), as this macro - * attempts to deal with the 32-bit counter wrapping back to zero every ~49 - * days, but should _not_ be used with SDL_GetTicks64(), which does not have - * that problem. - * - * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could do - * this: - * - * ```c - * const Uint32 timeout = SDL_GetTicks() + 100; - * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) { - * // ... do work until timeout has elapsed - * } - * ``` - * - * Note that this does not handle tick differences greater than 2^31 so take - * care when using the above kind of code with large timeout delays (tens of - * days). - */ -#define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0) - -/** - * Get the current value of the high resolution counter. - * - * This function is typically used for profiling. - * - * The counter values are only meaningful relative to each other. Differences - * between values can be converted to times by using - * SDL_GetPerformanceFrequency(). - * - * \returns the current counter value. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetPerformanceFrequency - */ -extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); - -/** - * Get the count per second of the high resolution counter. - * - * \returns a platform-specific count per second. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetPerformanceCounter - */ -extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); - -/** - * Wait a specified number of milliseconds before returning. - * - * This function waits a specified number of milliseconds before returning. It - * waits at least the specified time, but possibly longer due to OS - * scheduling. - * - * \param ms the number of milliseconds to delay. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); - -/** - * Function prototype for the timer callback function. - * - * The callback function is passed the current timer interval and returns the - * next timer interval. If the returned value is the same as the one passed - * in, the periodic alarm continues, otherwise a new alarm is scheduled. If - * the callback returns 0, the periodic alarm is cancelled. - */ -typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param); - -/** - * Definition of the timer ID type. - */ -typedef int SDL_TimerID; - -/** - * Call a callback function at a future time. - * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * - * The callback function is passed the current timer interval and the user - * supplied parameter from the SDL_AddTimer() call and should return the next - * timer interval. If the value returned from the callback is 0, the timer is - * canceled. - * - * The callback is run on a separate thread. - * - * Timers take into account the amount of time it took to execute the - * callback. For example, if the callback took 250 ms to execute and returned - * 1000 (ms), the timer would only wait another 750 ms before its next - * iteration. - * - * Timing may be inexact due to OS scheduling. Be sure to note the current - * time with SDL_GetTicks() or SDL_GetPerformanceCounter() in case your - * callback needs to adjust for variances. - * - * \param interval the timer delay, in milliseconds, passed to `callback`. - * \param callback the SDL_TimerCallback function to call when the specified - * `interval` elapses. - * \param param a pointer that is passed to `callback`. - * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RemoveTimer - */ -extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, - SDL_TimerCallback callback, - void *param); - -/** - * Remove a timer created with SDL_AddTimer(). - * - * \param id the ID of the timer to remove. - * \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't - * found. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_AddTimer - */ -extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_timer_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_touch.h b/code/thirdparty/SDL2-2.32.8/include/SDL_touch.h deleted file mode 100644 index 80a0fef8ac..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_touch.h +++ /dev/null @@ -1,150 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryTouch - * - * Include file for SDL touch event handling. - */ - -#ifndef SDL_touch_h_ -#define SDL_touch_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -typedef Sint64 SDL_TouchID; -typedef Sint64 SDL_FingerID; - -typedef enum -{ - SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ -} SDL_TouchDeviceType; - -typedef struct SDL_Finger -{ - SDL_FingerID id; - float x; - float y; - float pressure; -} SDL_Finger; - -/* Used as the device ID for mouse events simulated with touch input */ -#define SDL_TOUCH_MOUSEID ((Uint32)-1) - -/* Used as the SDL_TouchID for touch events simulated with mouse input */ -#define SDL_MOUSE_TOUCHID ((Sint64)-1) - - -/** - * Get the number of registered touch devices. - * - * On some platforms SDL first sees the touch device if it was actually used. - * Therefore SDL_GetNumTouchDevices() may return 0 although devices are - * available. After using all devices at least once the number will be - * correct. - * - * This was fixed for Android in SDL 2.0.1. - * - * \returns the number of registered touch devices. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTouchDevice - */ -extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void); - -/** - * Get the touch ID with the given index. - * - * \param index the touch device index. - * \returns the touch ID with the given index on success or 0 if the index is - * invalid; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumTouchDevices - */ -extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index); - -/** - * Get the touch device name as reported from the driver or NULL if the index - * is invalid. - * - * \since This function is available since SDL 2.0.22. - */ -extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index); - -/** - * Get the type of the given touch device. - * - * \since This function is available since SDL 2.0.10. - */ -extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); - -/** - * Get the number of active fingers for a given touch device. - * - * \param touchID the ID of a touch device. - * \returns the number of active fingers for a given touch device on success - * or 0 on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetTouchFinger - */ -extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID); - -/** - * Get the finger object for specified touch device ID and finger index. - * - * The returned resource is owned by SDL and should not be deallocated. - * - * \param touchID the ID of the requested touch device. - * \param index the index of the requested finger. - * \returns a pointer to the SDL_Finger object or NULL if no object at the - * given ID and index could be found. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_RecordGesture - */ -extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_touch_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_types.h b/code/thirdparty/SDL2-2.32.8/include/SDL_types.h deleted file mode 100644 index cb3b4a8df1..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_types.h +++ /dev/null @@ -1,24 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* DEPRECATED */ - -#include "SDL_stdinc.h" diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_version.h b/code/thirdparty/SDL2-2.32.8/include/SDL_version.h deleted file mode 100644 index e8087751b3..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_version.h +++ /dev/null @@ -1,205 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryVersion - * - * This header defines the current SDL version. - */ - -#ifndef SDL_version_h_ -#define SDL_version_h_ - -#include "SDL_stdinc.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Information about the version of SDL in use. - * - * Represents the library's version as three levels: major revision - * (increments with massive changes, additions, and enhancements), minor - * revision (increments with backwards-compatible changes to the major - * revision), and patchlevel (increments with fixes to the minor revision). - * - * \sa SDL_VERSION - * \sa SDL_GetVersion - */ -typedef struct SDL_version -{ - Uint8 major; /**< major version */ - Uint8 minor; /**< minor version */ - Uint8 patch; /**< update version */ -} SDL_version; - -/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL -*/ -#define SDL_MAJOR_VERSION 2 -#define SDL_MINOR_VERSION 32 -#define SDL_PATCHLEVEL 8 - -/** - * Macro to determine SDL version program was compiled against. - * - * This macro fills in a SDL_version structure with the version of the library - * you compiled against. This is determined by what header the compiler uses. - * Note that if you dynamically linked the library, you might have a slightly - * newer or older version at runtime. That version can be determined with - * SDL_GetVersion(), which, unlike SDL_VERSION(), is not a macro. - * - * \param x A pointer to a SDL_version struct to initialize. - * - * \sa SDL_version - * \sa SDL_GetVersion - */ -#define SDL_VERSION(x) \ -{ \ - (x)->major = SDL_MAJOR_VERSION; \ - (x)->minor = SDL_MINOR_VERSION; \ - (x)->patch = SDL_PATCHLEVEL; \ -} - -/* TODO: Remove this whole block in SDL 3 */ -#if SDL_MAJOR_VERSION < 3 - -/** - * This macro turns the version numbers into a numeric value: - * - * ``` - * (1,2,3) -> (1203) - * ``` - * - * This assumes that there will never be more than 100 patchlevels. - * - * In versions higher than 2.9.0, the minor version overflows into the - * thousands digit: for example, 2.23.0 is encoded as 4300, and 2.255.99 would - * be encoded as 25799. - * - * This macro will not be available in SDL 3.x. - */ -#define SDL_VERSIONNUM(X, Y, Z) \ - ((X)*1000 + (Y)*100 + (Z)) - -/** - * This is the version number macro for the current SDL version. - * - * In versions higher than 2.9.0, the minor version overflows into the - * thousands digit: for example, 2.23.0 is encoded as 4300. This macro will - * not be available in SDL 3.x. - * - * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. - */ -#define SDL_COMPILEDVERSION \ - SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL) -#endif /* SDL_MAJOR_VERSION < 3 */ - -/** - * This macro will evaluate to true if compiled with SDL at least X.Y.Z. - */ -#define SDL_VERSION_ATLEAST(X, Y, Z) \ - ((SDL_MAJOR_VERSION >= X) && \ - (SDL_MAJOR_VERSION > X || SDL_MINOR_VERSION >= Y) && \ - (SDL_MAJOR_VERSION > X || SDL_MINOR_VERSION > Y || SDL_PATCHLEVEL >= Z)) - -/** - * Get the version of SDL that is linked against your program. - * - * If you are linking to SDL dynamically, then it is possible that the current - * version will be different than the version you compiled against. This - * function returns the current version, while SDL_VERSION() is a macro that - * tells you what version you compiled with. - * - * This function may be called safely at any time, even before SDL_Init(). - * - * \param ver the SDL_version structure that contains the version information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRevision - */ -extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver); - -/** - * Get the code revision of SDL that is linked against your program. - * - * This value is the revision of the code you are linked with and may be - * different from the code you are compiling with, which is found in the - * constant SDL_REVISION. - * - * The revision is arbitrary string (a hash value) uniquely identifying the - * exact revision of the SDL library in use, and is only useful in comparing - * against other revisions. It is NOT an incrementing number. - * - * If SDL wasn't built from a git repository with the appropriate tools, this - * will return an empty string. - * - * Prior to SDL 2.0.16, before development moved to GitHub, this returned a - * hash for a Mercurial repository. - * - * You shouldn't use this function for anything but logging it for debugging - * purposes. The string is not intended to be reliable in any way. - * - * \returns an arbitrary string, uniquely identifying the exact revision of - * the SDL library in use. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetVersion - */ -extern DECLSPEC const char *SDLCALL SDL_GetRevision(void); - -/** - * Obsolete function, do not use. - * - * When SDL was hosted in a Mercurial repository, and was built carefully, - * this would return the revision number that the build was created from. This - * number was not reliable for several reasons, but more importantly, SDL is - * now hosted in a git repository, which does not offer numbers at all, only - * hashes. This function only ever returns zero now. Don't use it. - * - * Before SDL 2.0.16, this might have returned an unreliable, but non-zero - * number. - * - * \deprecated Use SDL_GetRevision() instead; if SDL was carefully built, it - * will return a git hash. - * - * \returns zero, always, in modern SDL releases. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetRevision - */ -extern SDL_DEPRECATED DECLSPEC int SDLCALL SDL_GetRevisionNumber(void); - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_version_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_video.h b/code/thirdparty/SDL2-2.32.8/include/SDL_video.h deleted file mode 100644 index 2db5552fa2..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_video.h +++ /dev/null @@ -1,2228 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryVideo - * - * Header file for SDL video functions. - */ - -#ifndef SDL_video_h_ -#define SDL_video_h_ - -#include "SDL_stdinc.h" -#include "SDL_pixels.h" -#include "SDL_rect.h" -#include "SDL_surface.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * The structure that defines a display mode - * - * \sa SDL_GetNumDisplayModes - * \sa SDL_GetDisplayMode - * \sa SDL_GetDesktopDisplayMode - * \sa SDL_GetCurrentDisplayMode - * \sa SDL_GetClosestDisplayMode - * \sa SDL_SetWindowDisplayMode - * \sa SDL_GetWindowDisplayMode - */ -typedef struct SDL_DisplayMode -{ - Uint32 format; /**< pixel format */ - int w; /**< width, in screen coordinates */ - int h; /**< height, in screen coordinates */ - int refresh_rate; /**< refresh rate (or zero for unspecified) */ - void *driverdata; /**< driver-specific data, initialize to 0 */ -} SDL_DisplayMode; - -/** - * The opaque type used to identify a window. - * - * \sa SDL_CreateWindow - * \sa SDL_CreateWindowFrom - * \sa SDL_DestroyWindow - * \sa SDL_FlashWindow - * \sa SDL_GetWindowData - * \sa SDL_GetWindowFlags - * \sa SDL_GetWindowGrab - * \sa SDL_GetWindowKeyboardGrab - * \sa SDL_GetWindowMouseGrab - * \sa SDL_GetWindowPosition - * \sa SDL_GetWindowSize - * \sa SDL_GetWindowTitle - * \sa SDL_HideWindow - * \sa SDL_MaximizeWindow - * \sa SDL_MinimizeWindow - * \sa SDL_RaiseWindow - * \sa SDL_RestoreWindow - * \sa SDL_SetWindowData - * \sa SDL_SetWindowFullscreen - * \sa SDL_SetWindowGrab - * \sa SDL_SetWindowKeyboardGrab - * \sa SDL_SetWindowMouseGrab - * \sa SDL_SetWindowIcon - * \sa SDL_SetWindowPosition - * \sa SDL_SetWindowSize - * \sa SDL_SetWindowBordered - * \sa SDL_SetWindowResizable - * \sa SDL_SetWindowTitle - * \sa SDL_ShowWindow - */ -typedef struct SDL_Window SDL_Window; - -/** - * The flags on a window - * - * \sa SDL_GetWindowFlags - */ -typedef enum SDL_WindowFlags -{ - SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window */ - SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */ - SDL_WINDOW_SHOWN = 0x00000004, /**< window is visible */ - SDL_WINDOW_HIDDEN = 0x00000008, /**< window is not visible */ - SDL_WINDOW_BORDERLESS = 0x00000010, /**< no window decoration */ - SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */ - SDL_WINDOW_MINIMIZED = 0x00000040, /**< window is minimized */ - SDL_WINDOW_MAXIMIZED = 0x00000080, /**< window is maximized */ - SDL_WINDOW_MOUSE_GRABBED = 0x00000100, /**< window has grabbed mouse input */ - SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */ - SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */ - SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ), - SDL_WINDOW_FOREIGN = 0x00000800, /**< window not created by SDL */ - SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000, /**< window should be created in high-DPI mode if supported. - On macOS NSHighResolutionCapable must be set true in the - application's Info.plist for this to have any effect. */ - SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to MOUSE_GRABBED) */ - SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */ - SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */ - SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window */ - SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip */ - SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu */ - SDL_WINDOW_KEYBOARD_GRABBED = 0x00100000, /**< window has grabbed keyboard input */ - SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */ - SDL_WINDOW_METAL = 0x20000000, /**< window usable for Metal view */ - - SDL_WINDOW_INPUT_GRABBED = SDL_WINDOW_MOUSE_GRABBED /**< equivalent to SDL_WINDOW_MOUSE_GRABBED for compatibility */ -} SDL_WindowFlags; - -/** - * Used to indicate that you don't care what the window position is. - */ -#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. - */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u -#define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) -#define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) -#define SDL_WINDOWPOS_ISCENTERED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) - -/** - * Event subtype for window events - */ -typedef enum SDL_WindowEventID -{ - SDL_WINDOWEVENT_NONE, /**< Never used */ - SDL_WINDOWEVENT_SHOWN, /**< Window has been shown */ - SDL_WINDOWEVENT_HIDDEN, /**< Window has been hidden */ - SDL_WINDOWEVENT_EXPOSED, /**< Window has been exposed and should be - redrawn */ - SDL_WINDOWEVENT_MOVED, /**< Window has been moved to data1, data2 - */ - SDL_WINDOWEVENT_RESIZED, /**< Window has been resized to data1xdata2 */ - SDL_WINDOWEVENT_SIZE_CHANGED, /**< The window size has changed, either as - a result of an API call or through the - system or user changing the window size. */ - SDL_WINDOWEVENT_MINIMIZED, /**< Window has been minimized */ - SDL_WINDOWEVENT_MAXIMIZED, /**< Window has been maximized */ - SDL_WINDOWEVENT_RESTORED, /**< Window has been restored to normal size - and position */ - SDL_WINDOWEVENT_ENTER, /**< Window has gained mouse focus */ - SDL_WINDOWEVENT_LEAVE, /**< Window has lost mouse focus */ - SDL_WINDOWEVENT_FOCUS_GAINED, /**< Window has gained keyboard focus */ - SDL_WINDOWEVENT_FOCUS_LOST, /**< Window has lost keyboard focus */ - SDL_WINDOWEVENT_CLOSE, /**< The window manager requests that the window be closed */ - SDL_WINDOWEVENT_TAKE_FOCUS, /**< Window is being offered a focus (should SetWindowInputFocus() on itself or a subwindow, or ignore) */ - SDL_WINDOWEVENT_HIT_TEST, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL. */ - SDL_WINDOWEVENT_ICCPROF_CHANGED,/**< The ICC profile of the window's display has changed. */ - SDL_WINDOWEVENT_DISPLAY_CHANGED /**< Window has been moved to display data1. */ -} SDL_WindowEventID; - -/** - * Event subtype for display events - */ -typedef enum SDL_DisplayEventID -{ - SDL_DISPLAYEVENT_NONE, /**< Never used */ - SDL_DISPLAYEVENT_ORIENTATION, /**< Display orientation has changed to data1 */ - SDL_DISPLAYEVENT_CONNECTED, /**< Display has been added to the system */ - SDL_DISPLAYEVENT_DISCONNECTED, /**< Display has been removed from the system */ - SDL_DISPLAYEVENT_MOVED /**< Display has changed position */ -} SDL_DisplayEventID; - -/** - * Display orientation - */ -typedef enum SDL_DisplayOrientation -{ - SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ - SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ - SDL_ORIENTATION_LANDSCAPE_FLIPPED, /**< The display is in landscape mode, with the left side up, relative to portrait mode */ - SDL_ORIENTATION_PORTRAIT, /**< The display is in portrait mode */ - SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */ -} SDL_DisplayOrientation; - -/** - * Window flash operation - */ -typedef enum SDL_FlashOperation -{ - SDL_FLASH_CANCEL, /**< Cancel any window flash state */ - SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */ - SDL_FLASH_UNTIL_FOCUSED /**< Flash the window until it gets focus */ -} SDL_FlashOperation; - -/** - * An opaque handle to an OpenGL context. - * - * \sa SDL_GL_CreateContext - */ -typedef void *SDL_GLContext; - -/** - * OpenGL configuration attributes. - * - * While you can set most OpenGL attributes normally, the attributes listed - * above must be known before SDL creates the window that will be used with - * the OpenGL context. These attributes are set and read with - * SDL_GL_SetAttribute and SDL_GL_GetAttribute. - * - * In some cases, these attributes are minimum requests; the GL does not - * promise to give you exactly what you asked for. It's possible to ask for a - * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask - * for no stencil buffer and still have one available. Context creation should - * fail if the GL can't provide your requested attributes at a minimum, but - * you should check to see exactly what you got. - * - * - * [Multisample anti-aliasing](http://en.wikipedia.org/wiki/Multisample_anti-aliasing) - * is a type of full screen anti-aliasing. Multipsampling defaults to off but - * can be turned on by setting SDL_GL_MULTISAMPLEBUFFERS to 1 and - * SDL_GL_MULTISAMPLESAMPLES to a value greater than 0. Typical values are 2 - * and 4. - * - * SDL_GL_CONTEXT_PROFILE_MASK determines the type of context created, while - * both SDL_GL_CONTEXT_MAJOR_VERSION and SDL_GL_CONTEXT_MINOR_VERSION - * determine which version. All three attributes must be set prior to creating - * the first window, and in general you can't change the value of - * SDL_GL_CONTEXT_PROFILE_MASK without first destroying all windows created - * with the previous setting. - * - * SDL_GL_CONTEXT_RELEASE_BEHAVIOR can be set to - * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE or - * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH. - */ -typedef enum SDL_GLattr -{ - SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ - SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ - SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 2. */ - SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. */ - SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */ - SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */ - SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */ - SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ - SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ - SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ - SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ - SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ - SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */ - SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ - SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ - SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ - SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ - SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ - SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_EGL, /**< deprecated: set SDL_GL_CONTEXT_PROFILE_MASK to SDL_GL_CONTEXT_PROFILE_ES to enable instead. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ - SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ - SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. (>= SDL 2.0.1) */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior; defaults to 1. (>= SDL 2.0.4) */ - SDL_GL_CONTEXT_RESET_NOTIFICATION, - SDL_GL_CONTEXT_NO_ERROR, - SDL_GL_FLOATBUFFERS -} SDL_GLattr; - -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; - -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; - -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; - -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; - -/* Function prototypes */ - -/** - * Get the number of video drivers compiled into SDL. - * - * \returns a number >= 1 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetVideoDriver - */ -extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); - -/** - * Get the name of a built in video driver. - * - * The video drivers are presented in the order in which they are normally - * checked during initialization. - * - * \param index the index of a video driver. - * \returns the name of the video driver with the given **index**. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumVideoDrivers - */ -extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); - -/** - * Initialize the video subsystem, optionally specifying a video driver. - * - * This function initializes the video subsystem, setting up a connection to - * the window manager, etc, and determines the available display modes and - * pixel formats, but does not initialize a window or graphics mode. - * - * If you use this function and you haven't used the SDL_INIT_VIDEO flag with - * either SDL_Init() or SDL_InitSubSystem(), you should call SDL_VideoQuit() - * before calling SDL_Quit(). - * - * It is safe to call this function multiple times. SDL_VideoInit() will call - * SDL_VideoQuit() itself if the video subsystem has already been initialized. - * - * You can use SDL_GetNumVideoDrivers() and SDL_GetVideoDriver() to find a - * specific `driver_name`. - * - * \param driver_name the name of a video driver to initialize, or NULL for - * the default driver. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumVideoDrivers - * \sa SDL_GetVideoDriver - * \sa SDL_InitSubSystem - * \sa SDL_VideoQuit - */ -extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name); - -/** - * Shut down the video subsystem, if initialized with SDL_VideoInit(). - * - * This function closes all windows, and restores the original video mode. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_VideoInit - */ -extern DECLSPEC void SDLCALL SDL_VideoQuit(void); - -/** - * Get the name of the currently initialized video driver. - * - * \returns the name of the current video driver or NULL if no driver has been - * initialized. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumVideoDrivers - * \sa SDL_GetVideoDriver - */ -extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void); - -/** - * Get the number of available video displays. - * - * \returns a number >= 1 or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetDisplayBounds - */ -extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); - -/** - * Get the name of a display in UTF-8 encoding. - * - * \param displayIndex the index of display from which the name should be - * queried. - * \returns the name of a display or NULL for an invalid display index or - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); - -/** - * Get the desktop area represented by a display. - * - * The primary display (`displayIndex` zero) is always located at 0,0. - * - * \param displayIndex the index of the display to query. - * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect); - -/** - * Get the usable desktop area represented by a display. - * - * The primary display (`displayIndex` zero) is always located at 0,0. - * - * This is the same area as SDL_GetDisplayBounds() reports, but with portions - * reserved by the system removed. For example, on Apple's macOS, this - * subtracts the area occupied by the menu bar and dock. - * - * Setting a window to be fullscreen generally bypasses these unusable areas, - * so these are good guidelines for the maximum space available to a - * non-fullscreen window. - * - * The parameter `rect` is ignored if it is NULL. - * - * This function also returns -1 if the parameter `displayIndex` is out of - * range. - * - * \param displayIndex the index of the display to query the usable bounds - * from. - * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_GetDisplayBounds - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect); - -/** - * Get the dots/pixels-per-inch for a display. - * - * Diagonal, horizontal and vertical DPI can all be optionally returned if the - * appropriate parameter is non-NULL. - * - * A failure of this function usually means that either no DPI information is - * available or the `displayIndex` is out of range. - * - * **WARNING**: This reports the DPI that the hardware reports, and it is not - * always reliable! It is almost always better to use SDL_GetWindowSize() to - * find the window size, which might be in logical points instead of pixels, - * and then SDL_GL_GetDrawableSize(), SDL_Vulkan_GetDrawableSize(), - * SDL_Metal_GetDrawableSize(), or SDL_GetRendererOutputSize(), and compare - * the two values to get an actual scaling value between the two. We will be - * rethinking how high-dpi details should be managed in SDL3 to make things - * more consistent, reliable, and clear. - * - * \param displayIndex the index of the display from which DPI information - * should be queried. - * \param ddpi a pointer filled in with the diagonal DPI of the display; may - * be NULL. - * \param hdpi a pointer filled in with the horizontal DPI of the display; may - * be NULL. - * \param vdpi a pointer filled in with the vertical DPI of the display; may - * be NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi); - -/** - * Get the orientation of a display. - * - * \param displayIndex the index of the display to query. - * \returns The SDL_DisplayOrientation enum value of the display, or - * `SDL_ORIENTATION_UNKNOWN` if it isn't available. - * - * \since This function is available since SDL 2.0.9. - * - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex); - -/** - * Get the number of available display modes. - * - * The `displayIndex` needs to be in the range from 0 to - * SDL_GetNumVideoDisplays() - 1. - * - * \param displayIndex the index of the display to query. - * \returns a number >= 1 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetDisplayMode - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); - -/** - * Get information about a specific display mode. - * - * The display modes are sorted in this priority: - * - * - width -> largest to smallest - * - height -> largest to smallest - * - bits per pixel -> more colors to fewer colors - * - packed pixel layout -> largest to smallest - * - refresh rate -> highest to lowest - * - * \param displayIndex the index of the display to query. - * \param modeIndex the index of the display mode to query. - * \param mode an SDL_DisplayMode structure filled in with the mode at - * `modeIndex`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetNumDisplayModes - */ -extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, - SDL_DisplayMode * mode); - -/** - * Get information about the desktop's display mode. - * - * There's a difference between this function and SDL_GetCurrentDisplayMode() - * when SDL runs fullscreen and has changed the resolution. In that case this - * function will return the previous native display mode, and not the current - * display mode. - * - * \param displayIndex the index of the display to query. - * \param mode an SDL_DisplayMode structure filled in with the current display - * mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetCurrentDisplayMode - * \sa SDL_GetDisplayMode - * \sa SDL_SetWindowDisplayMode - */ -extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode); - -/** - * Get information about the current display mode. - * - * There's a difference between this function and SDL_GetDesktopDisplayMode() - * when SDL runs fullscreen and has changed the resolution. In that case this - * function will return the current display mode, and not the previous native - * display mode. - * - * \param displayIndex the index of the display to query. - * \param mode an SDL_DisplayMode structure filled in with the current display - * mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetDesktopDisplayMode - * \sa SDL_GetDisplayMode - * \sa SDL_GetNumVideoDisplays - * \sa SDL_SetWindowDisplayMode - */ -extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode); - - -/** - * Get the closest match to the requested display mode. - * - * The available display modes are scanned and `closest` is filled in with the - * closest mode matching the requested mode and returned. The mode format and - * refresh rate default to the desktop mode if they are set to 0. The modes - * are scanned with size being first priority, format being second priority, - * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. - * - * \param displayIndex the index of the display to query. - * \param mode an SDL_DisplayMode structure containing the desired display - * mode. - * \param closest an SDL_DisplayMode structure filled in with the closest - * match of the available display modes. - * \returns the passed in value `closest` or NULL if no matching video mode - * was available; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetDisplayMode - * \sa SDL_GetNumDisplayModes - */ -extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest); - -/** - * Get the index of the display containing a point - * - * \param point the point to query. - * \returns the index of the display containing the point or a negative error - * code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GetDisplayBounds - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetPointDisplayIndex(const SDL_Point * point); - -/** - * Get the index of the display primarily containing a rect - * - * \param rect the rect to query. - * \returns the index of the display entirely containing the rect or closest - * to the center of the rect on success or a negative error code on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.24.0. - * - * \sa SDL_GetDisplayBounds - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetRectDisplayIndex(const SDL_Rect * rect); - -/** - * Get the index of the display associated with a window. - * - * \param window the window to query. - * \returns the index of the display containing the center of the window on - * success or a negative error code on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetDisplayBounds - * \sa SDL_GetNumVideoDisplays - */ -extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); - -/** - * Set the display mode to use when a window is visible at fullscreen. - * - * This only affects the display mode used when the window is fullscreen. To - * change the window size when the window is not fullscreen, use - * SDL_SetWindowSize(). - * - * \param window the window to affect. - * \param mode the SDL_DisplayMode structure representing the mode to use, or - * NULL to use the window's dimensions and the desktop's format - * and refresh rate. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowDisplayMode - * \sa SDL_SetWindowFullscreen - */ -extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window, - const SDL_DisplayMode * mode); - -/** - * Query the display mode to use when a window is visible at fullscreen. - * - * \param window the window to query. - * \param mode an SDL_DisplayMode structure filled in with the fullscreen - * display mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowDisplayMode - * \sa SDL_SetWindowFullscreen - */ -extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, - SDL_DisplayMode * mode); - -/** - * Get the raw ICC profile data for the screen the window is currently on. - * - * Data returned should be freed with SDL_free. - * - * \param window the window to query. - * \param size the size of the ICC profile. - * \returns the raw ICC profile data on success or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.18. - */ -extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_t* size); - -/** - * Get the pixel format associated with the window. - * - * \param window the window to query. - * \returns the pixel format of the window on success or - * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); - -/** - * Create a window with the specified position, dimensions, and flags. - * - * `flags` may be any of the following OR'd together: - * - * - `SDL_WINDOW_FULLSCREEN`: fullscreen window - * - `SDL_WINDOW_FULLSCREEN_DESKTOP`: fullscreen window at desktop resolution - * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context - * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance - * - `SDL_WINDOW_METAL`: window usable with a Metal instance - * - `SDL_WINDOW_HIDDEN`: window is not visible - * - `SDL_WINDOW_BORDERLESS`: no window decoration - * - `SDL_WINDOW_RESIZABLE`: window can be resized - * - `SDL_WINDOW_MINIMIZED`: window is minimized - * - `SDL_WINDOW_MAXIMIZED`: window is maximized - * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus - * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if - * supported (>= SDL 2.0.1) - * - * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is - * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be - * queried later using SDL_GetWindowFlags(). - * - * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist - * property to YES, otherwise you will not receive a High-DPI OpenGL canvas. - * - * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size - * in pixels may differ from its size in screen coordinates on platforms with - * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the - * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or - * SDL_GetRendererOutputSize() to query the drawable size in pixels. Note that - * when this flag is set, the drawable size can vary after the window is - * created and should be queried after major window events such as when the - * window is resized or moved between displays. - * - * If the window is set fullscreen, the width and height parameters `w` and - * `h` will not be used. However, invalid size parameters (e.g. too large) may - * still fail. Window size is actually limited to 16384 x 16384 for all - * platforms at window creation. - * - * If the window is created with any of the SDL_WINDOW_OPENGL or - * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function - * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the - * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). - * - * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. - * - * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, - * SDL_CreateWindow() will fail. - * - * On non-Apple devices, SDL requires you to either not link to the Vulkan - * loader or link to a dynamic library version. This limitation may be removed - * in a future version of SDL. - * - * \param title the title of the window, in UTF-8 encoding. - * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or - * `SDL_WINDOWPOS_UNDEFINED`. - * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or - * `SDL_WINDOWPOS_UNDEFINED`. - * \param w the width of the window, in screen coordinates. - * \param h the height of the window, in screen coordinates. - * \param flags 0, or one or more SDL_WindowFlags OR'd together. - * \returns the `SDL_Window` that was created or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateWindowFrom - * \sa SDL_DestroyWindow - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, - int x, int y, int w, - int h, Uint32 flags); - -/** - * Create an SDL window from an existing native window. - * - * In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows) - * the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured - * before using SDL_CreateWindowFrom(). - * - * \param data a pointer to driver-dependent window creation data, typically - * your native window cast to a void*. - * \returns the window that was created or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateWindow - * \sa SDL_DestroyWindow - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); - -/** - * Get the numeric ID of a window. - * - * The numeric ID is what SDL_WindowEvent references, and is necessary to map - * these events to specific SDL_Window objects. - * - * \param window the window to query. - * \returns the ID of the window on success or 0 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowFromID - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window); - -/** - * Get a window from a stored ID. - * - * The numeric ID is what SDL_WindowEvent references, and is necessary to map - * these events to specific SDL_Window objects. - * - * \param id the ID of the window. - * \returns the window associated with `id` or NULL if it doesn't exist; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowID - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); - -/** - * Get the window flags. - * - * \param window the window to query. - * \returns a mask of the SDL_WindowFlags associated with `window`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateWindow - * \sa SDL_HideWindow - * \sa SDL_MaximizeWindow - * \sa SDL_MinimizeWindow - * \sa SDL_SetWindowFullscreen - * \sa SDL_SetWindowGrab - * \sa SDL_ShowWindow - */ -extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); - -/** - * Set the title of a window. - * - * This string is expected to be in UTF-8 encoding. - * - * \param window the window to change. - * \param title the desired window title in UTF-8 format. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowTitle - */ -extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, - const char *title); - -/** - * Get the title of a window. - * - * \param window the window to query. - * \returns the title of the window in UTF-8 format or "" if there is no - * title. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowTitle - */ -extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window); - -/** - * Set the icon for a window. - * - * \param window the window to change. - * \param icon an SDL_Surface structure containing the icon for the window. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, - SDL_Surface * icon); - -/** - * Associate an arbitrary named pointer with a window. - * - * `name` is case-sensitive. - * - * \param window the window to associate with the pointer. - * \param name the name of the pointer. - * \param userdata the associated pointer. - * \returns the previous value associated with `name`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowData - */ -extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window, - const char *name, - void *userdata); - -/** - * Retrieve the data pointer associated with a window. - * - * \param window the window to query. - * \param name the name of the pointer. - * \returns the value associated with `name`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowData - */ -extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, - const char *name); - -/** - * Set the position of a window. - * - * The window coordinate origin is the upper left of the display. - * - * \param window the window to reposition. - * \param x the x coordinate of the window in screen coordinates, or - * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. - * \param y the y coordinate of the window in screen coordinates, or - * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowPosition - */ -extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, - int x, int y); - -/** - * Get the position of a window. - * - * If you do not need the value for one of the positions a NULL may be passed - * in the `x` or `y` parameter. - * - * \param window the window to query. - * \param x a pointer filled in with the x position of the window, in screen - * coordinates, may be NULL. - * \param y a pointer filled in with the y position of the window, in screen - * coordinates, may be NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowPosition - */ -extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, - int *x, int *y); - -/** - * Set the size of a window's client area. - * - * The window size in screen coordinates may differ from the size in pixels, - * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform - * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or - * SDL_GetRendererOutputSize() to get the real client area size in pixels. - * - * Fullscreen windows automatically match the size of the display mode, and - * you should use SDL_SetWindowDisplayMode() to change their size. - * - * \param window the window to change. - * \param w the width of the window in pixels, in screen coordinates, must be - * > 0. - * \param h the height of the window in pixels, in screen coordinates, must be - * > 0. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowSize - * \sa SDL_SetWindowDisplayMode - */ -extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, - int h); - -/** - * Get the size of a window's client area. - * - * NULL can safely be passed as the `w` or `h` parameter if the width or - * height value is not desired. - * - * The window size in screen coordinates may differ from the size in pixels, - * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform - * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(), - * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the - * real client area size in pixels. - * - * \param window the window to query the width and height from. - * \param w a pointer filled in with the width of the window, in screen - * coordinates, may be NULL. - * \param h a pointer filled in with the height of the window, in screen - * coordinates, may be NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_GetDrawableSize - * \sa SDL_Vulkan_GetDrawableSize - * \sa SDL_SetWindowSize - */ -extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, - int *h); - -/** - * Get the size of a window's borders (decorations) around the client area. - * - * Note: If this function fails (returns -1), the size values will be - * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the - * window in question was borderless. - * - * Note: This function may fail on systems where the window has not yet been - * decorated by the display server (for example, immediately after calling - * SDL_CreateWindow). It is recommended that you wait at least until the - * window has been presented and composited, so that the window system has a - * chance to decorate the window and provide the border dimensions to SDL. - * - * This function also returns -1 if getting the information is not supported. - * - * \param window the window to query the size values of the border - * (decorations) from. - * \param top pointer to variable for storing the size of the top border; NULL - * is permitted. - * \param left pointer to variable for storing the size of the left border; - * NULL is permitted. - * \param bottom pointer to variable for storing the size of the bottom - * border; NULL is permitted. - * \param right pointer to variable for storing the size of the right border; - * NULL is permitted. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_GetWindowSize - */ -extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, - int *top, int *left, - int *bottom, int *right); - -/** - * Get the size of a window in pixels. - * - * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI - * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a - * platform with high-DPI support (Apple calls this "Retina"), and not - * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. - * - * \param window the window from which the drawable size should be queried. - * \param w a pointer to variable for storing the width in pixels, may be - * NULL. - * \param h a pointer to variable for storing the height in pixels, may be - * NULL. - * - * \since This function is available since SDL 2.26.0. - * - * \sa SDL_CreateWindow - * \sa SDL_GetWindowSize - */ -extern DECLSPEC void SDLCALL SDL_GetWindowSizeInPixels(SDL_Window * window, - int *w, int *h); - -/** - * Set the minimum size of a window's client area. - * - * \param window the window to change. - * \param min_w the minimum width of the window in pixels. - * \param min_h the minimum height of the window in pixels. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowMinimumSize - * \sa SDL_SetWindowMaximumSize - */ -extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, - int min_w, int min_h); - -/** - * Get the minimum size of a window's client area. - * - * \param window the window to query. - * \param w a pointer filled in with the minimum width of the window, may be - * NULL. - * \param h a pointer filled in with the minimum height of the window, may be - * NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowMaximumSize - * \sa SDL_SetWindowMinimumSize - */ -extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, - int *w, int *h); - -/** - * Set the maximum size of a window's client area. - * - * \param window the window to change. - * \param max_w the maximum width of the window in pixels. - * \param max_h the maximum height of the window in pixels. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowMaximumSize - * \sa SDL_SetWindowMinimumSize - */ -extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, - int max_w, int max_h); - -/** - * Get the maximum size of a window's client area. - * - * \param window the window to query. - * \param w a pointer filled in with the maximum width of the window, may be - * NULL. - * \param h a pointer filled in with the maximum height of the window, may be - * NULL. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowMinimumSize - * \sa SDL_SetWindowMaximumSize - */ -extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, - int *w, int *h); - -/** - * Set the border state of a window. - * - * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add - * or remove the border from the actual window. This is a no-op if the - * window's border already matches the requested state. - * - * You can't change the border state of a fullscreen window. - * - * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowFlags - */ -extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, - SDL_bool bordered); - -/** - * Set the user-resizable state of a window. - * - * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and - * allow/disallow user resizing of the window. This is a no-op if the window's - * resizable state already matches the requested state. - * - * You can't change the resizable state of a fullscreen window. - * - * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_GetWindowFlags - */ -extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, - SDL_bool resizable); - -/** - * Set the window to always be above the others. - * - * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This - * will bring the window to the front and keep the window above the rest. - * - * \param window The window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_GetWindowFlags - */ -extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window, - SDL_bool on_top); - -/** - * Show a window. - * - * \param window the window to show. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HideWindow - * \sa SDL_RaiseWindow - */ -extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); - -/** - * Hide a window. - * - * \param window the window to hide. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_ShowWindow - */ -extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window); - -/** - * Raise a window above other windows and set the input focus. - * - * \param window the window to raise. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); - -/** - * Make a window as large as possible. - * - * \param window the window to maximize. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MinimizeWindow - * \sa SDL_RestoreWindow - */ -extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); - -/** - * Minimize a window to an iconic representation. - * - * \param window the window to minimize. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MaximizeWindow - * \sa SDL_RestoreWindow - */ -extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); - -/** - * Restore the size and position of a minimized or maximized window. - * - * \param window the window to restore. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_MaximizeWindow - * \sa SDL_MinimizeWindow - */ -extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); - -/** - * Set a window's fullscreen state. - * - * `flags` may be `SDL_WINDOW_FULLSCREEN`, for "real" fullscreen with a - * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen - * that takes the size of the desktop; and 0 for windowed mode. - * - * Note that for some renderers, this function may trigger an - * SDL_RENDER_TARGETS_RESET event. Your application should be prepared to - * handle this event by reuploading textures! - * - * \param window the window to change. - * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowDisplayMode - * \sa SDL_SetWindowDisplayMode - */ -extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window, - Uint32 flags); - -/** - * Return whether the window has a surface associated with it. - * - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.28.0. - * - * \sa SDL_GetWindowSurface - */ -extern DECLSPEC SDL_bool SDLCALL SDL_HasWindowSurface(SDL_Window *window); - -/** - * Get the SDL surface associated with the window. - * - * A new surface will be created with the optimal format for the window, if - * necessary. This surface will be freed when the window is destroyed. Do not - * free this surface. - * - * This surface will be invalidated if the window is resized. After resizing a - * window this function must be called again to return a valid surface. - * - * Note that on some platforms the pixels pointer of the surface may be - * modified after each call to SDL_UpdateWindowSurface(), so that the platform - * code can implement efficient double or triple buffering. - * - * You may not combine this with 3D or the rendering API on this window. - * - * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. - * - * \param window the window to query. - * \returns the surface associated with the window, or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroyWindowSurface - * \sa SDL_HasWindowSurface - * \sa SDL_UpdateWindowSurface - * \sa SDL_UpdateWindowSurfaceRects - */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); - -/** - * Copy the window surface to the screen. - * - * This is the function you use to reflect any changes to the surface on the - * screen. - * - * This function is equivalent to the SDL 1.2 API SDL_Flip(). - * - * \param window the window to update. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowSurface - * \sa SDL_UpdateWindowSurfaceRects - */ -extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window); - -/** - * Copy areas of the window surface to the screen. - * - * This is the function you use to reflect changes to portions of the surface - * on the screen. - * - * This function is equivalent to the SDL 1.2 API SDL_UpdateRects(). - * - * Note that this function will update _at least_ the rectangles specified, - * but this is only intended as an optimization; in practice, this might - * update more of the screen (or all of the screen!), depending on what method - * SDL uses to send pixels to the system. - * - * \param window the window to update. - * \param rects an array of SDL_Rect structures representing areas of the - * surface to copy, in pixels. - * \param numrects the number of rectangles. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowSurface - * \sa SDL_UpdateWindowSurface - */ -extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window, - const SDL_Rect * rects, - int numrects); - -/** - * Destroy the surface associated with the window. - * - * \param window the window to update. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.28.0. - * - * \sa SDL_GetWindowSurface - * \sa SDL_HasWindowSurface - */ -extern DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); - -/** - * Set a window's input grab mode. - * - * When input is grabbed, the mouse is confined to the window. This function - * will also grab the keyboard if `SDL_HINT_GRAB_KEYBOARD` is set. To grab the - * keyboard without also grabbing the mouse, use SDL_SetWindowKeyboardGrab(). - * - * If the caller enables a grab while another window is currently grabbed, the - * other window loses its grab in favor of the caller's window. - * - * \param window the window for which the input grab mode should be set. - * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetGrabbedWindow - * \sa SDL_GetWindowGrab - */ -extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window, - SDL_bool grabbed); - -/** - * Set a window's keyboard grab mode. - * - * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or - * the Meta/Super key. Note that not all system keyboard shortcuts can be - * captured by applications (one example is Ctrl+Alt+Del on Windows). - * - * This is primarily intended for specialized applications such as VNC clients - * or VM frontends. Normal games should not use keyboard grab. - * - * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the - * window is full-screen to ensure the user is not trapped in your - * application. If you have a custom keyboard shortcut to exit fullscreen - * mode, you may suppress this behavior with - * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`. - * - * If the caller enables a grab while another window is currently grabbed, the - * other window loses its grab in favor of the caller's window. - * - * \param window The window for which the keyboard grab mode should be set. - * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_GetWindowKeyboardGrab - * \sa SDL_SetWindowMouseGrab - * \sa SDL_SetWindowGrab - */ -extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window, - SDL_bool grabbed); - -/** - * Set a window's mouse grab mode. - * - * Mouse grab confines the mouse cursor to the window. - * - * \param window The window for which the mouse grab mode should be set. - * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_GetWindowMouseGrab - * \sa SDL_SetWindowKeyboardGrab - * \sa SDL_SetWindowGrab - */ -extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window, - SDL_bool grabbed); - -/** - * Get a window's input grab mode. - * - * \param window the window to query. - * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowGrab - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); - -/** - * Get a window's keyboard grab mode. - * - * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_SetWindowKeyboardGrab - * \sa SDL_GetWindowGrab - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window); - -/** - * Get a window's mouse grab mode. - * - * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.16. - * - * \sa SDL_SetWindowKeyboardGrab - * \sa SDL_GetWindowGrab - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window); - -/** - * Get the window that currently has an input grab enabled. - * - * \returns the window if input is grabbed or NULL otherwise. - * - * \since This function is available since SDL 2.0.4. - * - * \sa SDL_GetWindowGrab - * \sa SDL_SetWindowGrab - */ -extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); - -/** - * Confines the cursor to the specified area of a window. - * - * Note that this does NOT grab the cursor, it only defines the area a cursor - * is restricted to when the window has mouse focus. - * - * \param window The window that will be associated with the barrier. - * \param rect A rectangle area in window-relative coordinates. If NULL the - * barrier for the specified window will be destroyed. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_GetWindowMouseRect - * \sa SDL_SetWindowMouseGrab - */ -extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SDL_Rect * rect); - -/** - * Get the mouse confinement rectangle of a window. - * - * \param window The window to query. - * \returns A pointer to the mouse confinement rectangle of a window, or NULL - * if there isn't one. - * - * \since This function is available since SDL 2.0.18. - * - * \sa SDL_SetWindowMouseRect - */ -extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * window); - -/** - * Set the brightness (gamma multiplier) for a given window's display. - * - * Despite the name and signature, this method sets the brightness of the - * entire display, not an individual window. A window is considered to be - * owned by the display that contains the window's center pixel. (The index of - * this display can be retrieved using SDL_GetWindowDisplayIndex().) The - * brightness set will not follow the window if it is moved to another - * display. - * - * Many platforms will refuse to set the display brightness in modern times. - * You are better off using a shader to adjust gamma during rendering, or - * something similar. - * - * \param window the window used to select the display whose brightness will - * be changed. - * \param brightness the brightness (gamma multiplier) value to set where 0.0 - * is completely dark and 1.0 is normal brightness. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowBrightness - * \sa SDL_SetWindowGammaRamp - */ -extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness); - -/** - * Get the brightness (gamma multiplier) for a given window's display. - * - * Despite the name and signature, this method retrieves the brightness of the - * entire display, not an individual window. A window is considered to be - * owned by the display that contains the window's center pixel. (The index of - * this display can be retrieved using SDL_GetWindowDisplayIndex().) - * - * \param window the window used to select the display whose brightness will - * be queried. - * \returns the brightness for the display where 0.0 is completely dark and - * 1.0 is normal brightness. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowBrightness - */ -extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); - -/** - * Set the opacity for a window. - * - * The parameter `opacity` will be clamped internally between 0.0f - * (transparent) and 1.0f (opaque). - * - * This function also returns -1 if setting the opacity isn't supported. - * - * \param window the window which will be made transparent or opaque. - * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_GetWindowOpacity - */ -extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity); - -/** - * Get the opacity of a window. - * - * If transparency isn't supported on this platform, opacity will be reported - * as 1.0f without error. - * - * The parameter `opacity` is ignored if it is NULL. - * - * This function also returns -1 if an invalid window was provided. - * - * \param window the window to get the current opacity value from. - * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_SetWindowOpacity - */ -extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity); - -/** - * Set the window as a modal for another window. - * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - */ -extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window); - -/** - * Explicitly set input focus to the window. - * - * You almost certainly want SDL_RaiseWindow() instead of this function. Use - * this with caution, as you might give focus to a window that is completely - * obscured by other windows. - * - * \param window the window that should get the input focus. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.5. - * - * \sa SDL_RaiseWindow - */ -extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); - -/** - * Set the gamma ramp for the display that owns a given window. - * - * Set the gamma translation table for the red, green, and blue channels of - * the video hardware. Each table is an array of 256 16-bit quantities, - * representing a mapping between the input and output for that channel. The - * input is the index into the array, and the output is the 16-bit gamma value - * at that index, scaled to the output color precision. - * - * Despite the name and signature, this method sets the gamma ramp of the - * entire display, not an individual window. A window is considered to be - * owned by the display that contains the window's center pixel. (The index of - * this display can be retrieved using SDL_GetWindowDisplayIndex().) The gamma - * ramp set will not follow the window if it is moved to another display. - * - * \param window the window used to select the display whose gamma ramp will - * be changed. - * \param red a 256 element array of 16-bit quantities representing the - * translation table for the red channel, or NULL. - * \param green a 256 element array of 16-bit quantities representing the - * translation table for the green channel, or NULL. - * \param blue a 256 element array of 16-bit quantities representing the - * translation table for the blue channel, or NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GetWindowGammaRamp - */ -extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, - const Uint16 * red, - const Uint16 * green, - const Uint16 * blue); - -/** - * Get the gamma ramp for a given window's display. - * - * Despite the name and signature, this method retrieves the gamma ramp of the - * entire display, not an individual window. A window is considered to be - * owned by the display that contains the window's center pixel. (The index of - * this display can be retrieved using SDL_GetWindowDisplayIndex().) - * - * \param window the window used to select the display whose gamma ramp will - * be queried. - * \param red a 256 element array of 16-bit quantities filled in with the - * translation table for the red channel, or NULL. - * \param green a 256 element array of 16-bit quantities filled in with the - * translation table for the green channel, or NULL. - * \param blue a 256 element array of 16-bit quantities filled in with the - * translation table for the blue channel, or NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_SetWindowGammaRamp - */ -extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, - Uint16 * red, - Uint16 * green, - Uint16 * blue); - -/** - * Possible return values from the SDL_HitTest callback. - * - * \sa SDL_HitTest - */ -typedef enum SDL_HitTestResult -{ - SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ - SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ - SDL_HITTEST_RESIZE_TOPLEFT, - SDL_HITTEST_RESIZE_TOP, - SDL_HITTEST_RESIZE_TOPRIGHT, - SDL_HITTEST_RESIZE_RIGHT, - SDL_HITTEST_RESIZE_BOTTOMRIGHT, - SDL_HITTEST_RESIZE_BOTTOM, - SDL_HITTEST_RESIZE_BOTTOMLEFT, - SDL_HITTEST_RESIZE_LEFT -} SDL_HitTestResult; - -/** - * Callback used for hit-testing. - * - * \param win the SDL_Window where hit-testing was set on. - * \param area an SDL_Point which should be hit-tested. - * \param data what was passed as `callback_data` to SDL_SetWindowHitTest(). - * \return an SDL_HitTestResult value. - * - * \sa SDL_SetWindowHitTest - */ -typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, - const SDL_Point *area, - void *data); - -/** - * Provide a callback that decides if a window region has special properties. - * - * Normally windows are dragged and resized by decorations provided by the - * system window manager (a title bar, borders, etc), but for some apps, it - * makes sense to drag them from somewhere else inside the window itself; for - * example, one might have a borderless window that wants to be draggable from - * any part, or simulate its own title bar, etc. - * - * This function lets the app provide a callback that designates pieces of a - * given window as special. This callback is run during event processing if we - * need to tell the OS to treat a region of the window specially; the use of - * this callback is known as "hit testing." - * - * Mouse input may not be delivered to your application if it is within a - * special area; the OS will often apply that input to moving the window or - * resizing the window and not deliver it to the application. - * - * Specifying NULL for a callback disables hit-testing. Hit-testing is - * disabled by default. - * - * Platforms that don't support this functionality will return -1 - * unconditionally, even if you're attempting to disable hit-testing. - * - * Your callback may fire at any time, and its firing does not indicate any - * specific behavior (for example, on Windows, this certainly might fire when - * the OS is deciding whether to drag your window, but it fires for lots of - * other reasons, too, some unrelated to anything you probably care about _and - * when the mouse isn't actually at the location it is testing_). Since this - * can fire at any time, you should try to keep your callback efficient, - * devoid of allocations, etc. - * - * \param window the window to set hit-testing on. - * \param callback the function to call when doing a hit-test. - * \param callback_data an app-defined void pointer passed to **callback**. - * \returns 0 on success or -1 on error (including unsupported); call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.4. - */ -extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, - SDL_HitTest callback, - void *callback_data); - -/** - * Request a window to demand attention from the user. - * - * \param window the window to be flashed. - * \param operation the flash operation. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.16. - */ -extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperation operation); - -/** - * Destroy a window. - * - * If `window` is NULL, this function will return immediately after setting - * the SDL error message to "Invalid window". See SDL_GetError(). - * - * \param window the window to destroy. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateWindow - * \sa SDL_CreateWindowFrom - */ -extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window); - - -/** - * Check whether the screensaver is currently enabled. - * - * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2 - * the screensaver was enabled by default. - * - * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. - * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DisableScreenSaver - * \sa SDL_EnableScreenSaver - */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void); - -/** - * Allow the screen to be blanked by a screen saver. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DisableScreenSaver - * \sa SDL_IsScreenSaverEnabled - */ -extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void); - -/** - * Prevent the screen from being blanked by a screen saver. - * - * If you disable the screensaver, it is automatically re-enabled when SDL - * quits. - * - * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2 - * the screensaver was enabled by default. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_EnableScreenSaver - * \sa SDL_IsScreenSaverEnabled - */ -extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); - - -/** - * \name OpenGL support functions - */ -/* @{ */ - -/** - * Dynamically load an OpenGL library. - * - * This should be done after initializing the video driver, but before - * creating any OpenGL windows. If no OpenGL library is loaded, the default - * library will be loaded upon creation of the first OpenGL window. - * - * If you do this, you need to retrieve all of the GL functions used in your - * program from the dynamic library using SDL_GL_GetProcAddress(). - * - * \param path the platform dependent OpenGL library name, or NULL to open the - * default OpenGL library. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_GetProcAddress - * \sa SDL_GL_UnloadLibrary - */ -extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); - -/** - * Get an OpenGL function by name. - * - * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all - * GL functions must be retrieved this way. Usually this is used to retrieve - * function pointers to OpenGL extensions. - * - * There are some quirks to looking up OpenGL functions that require some - * extra care from the application. If you code carefully, you can handle - * these quirks without any platform-specific code, though: - * - * - On Windows, function pointers are specific to the current GL context; - * this means you need to have created a GL context and made it current - * before calling SDL_GL_GetProcAddress(). If you recreate your context or - * create a second context, you should assume that any existing function - * pointers aren't valid to use with it. This is (currently) a - * Windows-specific limitation, and in practice lots of drivers don't suffer - * this limitation, but it is still the way the wgl API is documented to - * work and you should expect crashes if you don't respect it. Store a copy - * of the function pointers that comes and goes with context lifespan. - * - On X11, function pointers returned by this function are valid for any - * context, and can even be looked up before a context is created at all. - * This means that, for at least some common OpenGL implementations, if you - * look up a function that doesn't exist, you'll get a non-NULL result that - * is _NOT_ safe to call. You must always make sure the function is actually - * available for a given GL context before calling it, by checking for the - * existence of the appropriate extension with SDL_GL_ExtensionSupported(), - * or verifying that the version of OpenGL you're using offers the function - * as core functionality. - * - Some OpenGL drivers, on all platforms, *will* return NULL if a function - * isn't supported, but you can't count on this behavior. Check for - * extensions you use, and if you get a NULL anyway, act as if that - * extension wasn't available. This is probably a bug in the driver, but you - * can code defensively for this scenario anyhow. - * - Just because you're on Linux/Unix, don't assume you'll be using X11. - * Next-gen display servers are waiting to replace it, and may or may not - * make the same promises about function pointers. - * - OpenGL function pointers must be declared `APIENTRY` as in the example - * code. This will ensure the proper calling convention is followed on - * platforms where this matters (Win32) thereby avoiding stack corruption. - * - * \param proc the name of an OpenGL function. - * \returns a pointer to the named OpenGL function. The returned pointer - * should be cast to the appropriate function signature. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_ExtensionSupported - * \sa SDL_GL_LoadLibrary - * \sa SDL_GL_UnloadLibrary - */ -extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc); - -/** - * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_LoadLibrary - */ -extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); - -/** - * Check if an OpenGL extension is supported for the current context. - * - * This function operates on the current GL context; you must have created a - * context and it must be current before calling this function. Do not assume - * that all contexts you create will have the same set of extensions - * available, or that recreating an existing context will offer the same - * extensions again. - * - * While it's probably not a massive overhead, this function is not an O(1) - * operation. Check the extensions you care about after creating the GL - * context and save that information somewhere instead of calling the function - * every time you need to know. - * - * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char - *extension); - -/** - * Reset all previously set OpenGL context attributes to their default values. - * - * \since This function is available since SDL 2.0.2. - * - * \sa SDL_GL_GetAttribute - * \sa SDL_GL_SetAttribute - */ -extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); - -/** - * Set an OpenGL window attribute before window creation. - * - * This function sets the OpenGL attribute `attr` to `value`. The requested - * attributes should be set before creating an OpenGL window. You should use - * SDL_GL_GetAttribute() to check the values after creating the OpenGL - * context, since the values obtained can differ from the requested ones. - * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to - * set. - * \param value the desired value for the attribute. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_GetAttribute - * \sa SDL_GL_ResetAttributes - */ -extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); - -/** - * Get the actual value for an attribute from the current context. - * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to - * get. - * \param value a pointer filled in with the current value of `attr`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_ResetAttributes - * \sa SDL_GL_SetAttribute - */ -extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); - -/** - * Create an OpenGL context for an OpenGL window, and make it current. - * - * Windows users new to OpenGL should note that, for historical reasons, GL - * functions added after OpenGL version 1.1 are not available by default. - * Those functions must be loaded at run-time, either with an OpenGL - * extension-handling library or with SDL_GL_GetProcAddress() and its related - * functions. - * - * SDL_GLContext is an alias for `void *`. It's opaque to the application. - * - * \param window the window to associate with the context. - * \returns the OpenGL context associated with `window` or NULL on error; call - * SDL_GetError() for more details. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_DeleteContext - * \sa SDL_GL_MakeCurrent - */ -extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window * - window); - -/** - * Set up an OpenGL context for rendering into an OpenGL window. - * - * The context must have been created with a compatible window. - * - * \param window the window to associate with the context. - * \param context the OpenGL context to associate with the window. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_CreateContext - */ -extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window, - SDL_GLContext context); - -/** - * Get the currently active OpenGL window. - * - * \returns the currently active OpenGL window on success or NULL on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void); - -/** - * Get the currently active OpenGL context. - * - * \returns the currently active OpenGL context or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_MakeCurrent - */ -extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); - -/** - * Get the size of a window's underlying drawable in pixels. - * - * This returns info useful for calling glViewport(). - * - * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI - * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a - * platform with high-DPI support (Apple calls this "Retina"), and not - * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. - * - * \param window the window from which the drawable size should be queried. - * \param w a pointer to variable for storing the width in pixels, may be - * NULL. - * \param h a pointer to variable for storing the height in pixels, may be - * NULL. - * - * \since This function is available since SDL 2.0.1. - * - * \sa SDL_CreateWindow - * \sa SDL_GetWindowSize - */ -extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, - int *h); - -/** - * Set the swap interval for the current OpenGL context. - * - * Some systems allow specifying -1 for the interval, to enable adaptive - * vsync. Adaptive vsync works the same as vsync, but if you've already missed - * the vertical retrace for a given frame, it swaps buffers immediately, which - * might be less jarring for the user during occasional framerate drops. If an - * application requests adaptive vsync and the system does not support it, - * this function will fail and return -1. In such a case, you should probably - * retry the call with 1 for the interval. - * - * Adaptive vsync is implemented for some glX drivers with - * GLX_EXT_swap_control_tear, and for some Windows drivers with - * WGL_EXT_swap_control_tear. - * - * Read more on the Khronos wiki: - * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync - * - * \param interval 0 for immediate updates, 1 for updates synchronized with - * the vertical retrace, -1 for adaptive vsync. - * \returns 0 on success or -1 if setting the swap interval is not supported; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_GetSwapInterval - */ -extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); - -/** - * Get the swap interval for the current OpenGL context. - * - * If the system can't determine the swap interval, or there isn't a valid - * current context, this function will return 0 as a safe default. - * - * \returns 0 if there is no vertical retrace synchronization, 1 if the buffer - * swap is synchronized with the vertical retrace, and -1 if late - * swaps happen immediately instead of waiting for the next retrace; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_SetSwapInterval - */ -extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); - -/** - * Update a window with OpenGL rendering. - * - * This is used with double-buffered OpenGL contexts, which are the default. - * - * On macOS, make sure you bind 0 to the draw framebuffer before swapping the - * window, otherwise nothing will happen. If you aren't using - * glBindFramebuffer(), this is the default and you won't have to do anything - * extra. - * - * \param window the window to change. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window); - -/** - * Delete an OpenGL context. - * - * \param context the OpenGL context to be deleted. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_GL_CreateContext - */ -extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context); - -/* @} *//* OpenGL support functions */ - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_video_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_vulkan.h b/code/thirdparty/SDL2-2.32.8/include/SDL_vulkan.h deleted file mode 100644 index e005ed373b..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_vulkan.h +++ /dev/null @@ -1,219 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 2017, Mark Callow - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryVulkan - * - * Header file for functions to creating Vulkan surfaces on SDL windows. - */ - -#ifndef SDL_vulkan_h_ -#define SDL_vulkan_h_ - -#include "SDL_video.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/* Avoid including vulkan.h, don't define VkInstance if it's already included */ -#ifdef VULKAN_H_ -#define NO_SDL_VULKAN_TYPEDEFS -#endif -#ifndef NO_SDL_VULKAN_TYPEDEFS -#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; - -#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) -#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object; -#else -#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object; -#endif - -VK_DEFINE_HANDLE(VkInstance) -VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) - -/* Make sure to undef to avoid issues in case of later vulkan include */ -#undef VK_DEFINE_HANDLE -#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE - -#endif /* !NO_SDL_VULKAN_TYPEDEFS */ - -typedef VkInstance SDL_vulkanInstance; -typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */ - -/** - * \name Vulkan support functions - * - * \note SDL_Vulkan_GetInstanceExtensions & SDL_Vulkan_CreateSurface API - * is compatable with Tizen's implementation of Vulkan in SDL. - */ -/* @{ */ - -/** - * Dynamically load the Vulkan loader library. - * - * This should be called after initializing the video driver, but before - * creating any Vulkan windows. If no Vulkan loader library is loaded, the - * default library will be loaded upon creation of the first Vulkan window. - * - * It is fairly common for Vulkan applications to link with libvulkan instead - * of explicitly loading it at run time. This will work with SDL provided the - * application links to a dynamic library and both it and SDL use the same - * search path. - * - * If you specify a non-NULL `path`, an application should retrieve all of the - * Vulkan functions it uses from the dynamic library using - * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points - * to the same vulkan loader library the application linked to. - * - * On Apple devices, if `path` is NULL, SDL will attempt to find the - * `vkGetInstanceProcAddr` address within all the Mach-O images of the current - * process. This is because it is fairly common for Vulkan applications to - * link with libvulkan (and historically MoltenVK was provided as a static - * library). If it is not found, on macOS, SDL will attempt to load - * `vulkan.framework/vulkan`, `libvulkan.1.dylib`, - * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On - * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a - * dynamic framework or .dylib must ensure it is included in its application - * bundle. - * - * On non-Apple devices, application linking with a static libvulkan is not - * supported. Either do not link to the Vulkan loader or link to a dynamic - * library version. - * - * \param path The platform dependent Vulkan loader library name or NULL. - * \returns 0 on success or -1 if the library couldn't be loaded; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.6. - * - * \sa SDL_Vulkan_GetVkGetInstanceProcAddr - * \sa SDL_Vulkan_UnloadLibrary - */ -extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); - -/** - * Get the address of the `vkGetInstanceProcAddr` function. - * - * This should be called after either calling SDL_Vulkan_LoadLibrary() or - * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. - * - * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error. - * - * \since This function is available since SDL 2.0.6. - */ -extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); - -/** - * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary() - * - * \since This function is available since SDL 2.0.6. - * - * \sa SDL_Vulkan_LoadLibrary - */ -extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); - -/** - * Get the names of the Vulkan instance extensions needed to create a surface - * with SDL_Vulkan_CreateSurface. - * - * If `pNames` is NULL, then the number of required Vulkan instance extensions - * is returned in `pCount`. Otherwise, `pCount` must point to a variable set - * to the number of elements in the `pNames` array, and on return the variable - * is overwritten with the number of names actually written to `pNames`. If - * `pCount` is less than the number of required extensions, at most `pCount` - * structures will be written. If `pCount` is smaller than the number of - * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to - * indicate that not all the required extensions were returned. - * - * The `window` parameter is currently needed to be valid as of SDL 2.0.8, - * however, this parameter will likely be removed in future releases - * - * \param window A window for which the required Vulkan instance extensions - * should be retrieved (will be deprecated in a future release). - * \param pCount A pointer to an unsigned int corresponding to the number of - * extensions to be returned. - * \param pNames NULL or a pointer to an array to be filled with required - * Vulkan instance extensions. - * \returns SDL_TRUE on success, SDL_FALSE on error. - * - * \since This function is available since SDL 2.0.6. - * - * \sa SDL_Vulkan_CreateSurface - */ -extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window, - unsigned int *pCount, - const char **pNames); - -/** - * Create a Vulkan rendering surface for a window. - * - * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and - * `instance` must have been created with extensions returned by - * SDL_Vulkan_GetInstanceExtensions() enabled. - * - * \param window The window to which to attach the Vulkan surface. - * \param instance The Vulkan instance handle. - * \param surface A pointer to a VkSurfaceKHR handle to output the newly - * created surface. - * \returns SDL_TRUE on success, SDL_FALSE on error. - * - * \since This function is available since SDL 2.0.6. - * - * \sa SDL_Vulkan_GetInstanceExtensions - * \sa SDL_Vulkan_GetDrawableSize - */ -extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, - VkInstance instance, - VkSurfaceKHR* surface); - -/** - * Get the size of the window's underlying drawable dimensions in pixels. - * - * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI - * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a - * platform with high-DPI support (Apple calls this "Retina"), and not - * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. - * - * \param window an SDL_Window for which the size is to be queried. - * \param w Pointer to the variable to write the width to or NULL. - * \param h Pointer to the variable to write the height to or NULL. - * - * \since This function is available since SDL 2.0.6. - * - * \sa SDL_GetWindowSize - * \sa SDL_CreateWindow - * \sa SDL_Vulkan_CreateSurface - */ -extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window, - int *w, int *h); - -/* @} *//* Vulkan support functions */ - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_vulkan_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/begin_code.h b/code/thirdparty/SDL2-2.32.8/include/begin_code.h deleted file mode 100644 index 2044e5cb06..0000000000 --- a/code/thirdparty/SDL2-2.32.8/include/begin_code.h +++ /dev/null @@ -1,189 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/* WIKI CATEGORY: BeginCode */ - -/** - * 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. :) - */ - -/* This shouldn't be nested -- included it around code only. */ -#ifdef SDL_begin_code_h -#error Nested inclusion of begin_code.h -#endif -#define SDL_begin_code_h - -#ifndef SDL_DEPRECATED -# if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ -# define SDL_DEPRECATED __attribute__((deprecated)) -# elif defined(_MSC_VER) -# define SDL_DEPRECATED __declspec(deprecated) -# else -# define SDL_DEPRECATED -# endif -#endif - -#ifndef SDL_UNUSED -# ifdef __GNUC__ -# define SDL_UNUSED __attribute__((unused)) -# else -# define SDL_UNUSED -# endif -#endif - -/* Some compilers use a special export keyword */ -#ifndef DECLSPEC -# if defined(__WIN32__) || defined(__WINRT__) || defined(__CYGWIN__) || defined(__GDK__) -# ifdef DLL_EXPORT -# define DECLSPEC __declspec(dllexport) -# else -# define DECLSPEC -# endif -# elif defined(__OS2__) -# ifdef BUILD_SDL -# define DECLSPEC __declspec(dllexport) -# else -# define DECLSPEC -# endif -# else -# if defined(__GNUC__) && __GNUC__ >= 4 -# define DECLSPEC __attribute__ ((visibility("default"))) -# else -# define DECLSPEC -# endif -# endif -#endif - -/* By default SDL uses the C calling convention */ -#ifndef SDLCALL -#if (defined(__WIN32__) || defined(__WINRT__) || defined(__GDK__)) && !defined(__GNUC__) -#define SDLCALL __cdecl -#elif defined(__OS2__) || defined(__EMX__) -#define SDLCALL _System -# if defined (__GNUC__) && !defined(_System) -# define _System /* for old EMX/GCC compat. */ -# endif -#else -#define SDLCALL -#endif -#endif /* SDLCALL */ - -/* Removed DECLSPEC on Symbian OS because SDL cannot be a DLL in EPOC */ -#ifdef __SYMBIAN32__ -#undef DECLSPEC -#define DECLSPEC -#endif /* __SYMBIAN32__ */ - -/* Force structure packing at 4 byte alignment. - This is necessary if the header is included in code which has structure - packing set to an alternate value, say for loading structures from disk. - The packing is reset to the previous value in close_code.h - */ -#if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__) -#ifdef _MSC_VER -#pragma warning(disable: 4103) -#endif -#ifdef __clang__ -#pragma clang diagnostic ignored "-Wpragma-pack" -#endif -#ifdef __BORLANDC__ -#pragma nopackwarning -#endif -#ifdef _WIN64 -/* Use 8-byte alignment on 64-bit architectures, so pointers are aligned */ -#pragma pack(push,8) -#else -#pragma pack(push,4) -#endif -#endif /* Compiler needs structure packing set */ - -#ifndef SDL_INLINE -#if defined(__GNUC__) -#define SDL_INLINE __inline__ -#elif defined(_MSC_VER) || defined(__BORLANDC__) || \ - defined(__DMC__) || defined(__SC__) || \ - defined(__WATCOMC__) || defined(__LCC__) || \ - defined(__DECC) || defined(__CC_ARM) -#define SDL_INLINE __inline -#ifndef __inline__ -#define __inline__ __inline -#endif -#else -#define SDL_INLINE inline -#ifndef __inline__ -#define __inline__ inline -#endif -#endif -#endif /* SDL_INLINE not defined */ - -#ifndef SDL_FORCE_INLINE -#if defined(_MSC_VER) -#define SDL_FORCE_INLINE __forceinline -#elif ( (defined(__GNUC__) && (__GNUC__ >= 4)) || defined(__clang__) ) -#define SDL_FORCE_INLINE __attribute__((always_inline)) static __inline__ -#else -#define SDL_FORCE_INLINE static SDL_INLINE -#endif -#endif /* SDL_FORCE_INLINE not defined */ - -#ifndef SDL_NORETURN -#if defined(__GNUC__) -#define SDL_NORETURN __attribute__((noreturn)) -#elif defined(_MSC_VER) -#define SDL_NORETURN __declspec(noreturn) -#else -#define SDL_NORETURN -#endif -#endif /* SDL_NORETURN not defined */ - -/* Apparently this is needed by several Windows compilers */ -#if !defined(__MACH__) -#ifndef NULL -#ifdef __cplusplus -#define NULL 0 -#else -#define NULL ((void *)0) -#endif -#endif /* NULL */ -#endif /* ! Mac OS X - breaks precompiled headers */ - -#ifndef SDL_FALLTHROUGH -#if (defined(__cplusplus) && __cplusplus >= 201703L) || \ - (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L) -#define SDL_FALLTHROUGH [[fallthrough]] -#else -#if defined(__has_attribute) && !defined(__SUNPRO_C) && !defined(__SUNPRO_CC) -#define SDL_HAS_FALLTHROUGH __has_attribute(__fallthrough__) -#else -#define SDL_HAS_FALLTHROUGH 0 -#endif /* __has_attribute */ -#if SDL_HAS_FALLTHROUGH && \ - ((defined(__GNUC__) && __GNUC__ >= 7) || \ - (defined(__clang_major__) && __clang_major__ >= 10)) -#define SDL_FALLTHROUGH __attribute__((__fallthrough__)) -#else -#define SDL_FALLTHROUGH do {} while (0) /* fallthrough */ -#endif /* SDL_HAS_FALLTHROUGH */ -#undef SDL_HAS_FALLTHROUGH -#endif /* C++17 or C2x */ -#endif /* SDL_FALLTHROUGH not defined */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL.h new file mode 100644 index 0000000000..82993e7634 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL.h @@ -0,0 +1,90 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * Main include header for the SDL library, version 3.2.18 + * + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. + */ + +#ifndef SDL_h_ +#define SDL_h_ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#endif /* SDL_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_assert.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_assert.h new file mode 100644 index 0000000000..6c90acc029 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_assert.h @@ -0,0 +1,662 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryAssert + * + * A helpful assertion macro! + * + * SDL assertions operate like your usual `assert` macro, but with some added + * features: + * + * - It uses a trick with the `sizeof` operator, so disabled assertions + * vaporize out of the compiled code, but variables only referenced in the + * assertion won't trigger compiler warnings about being unused. + * - It is safe to use with a dangling-else: `if (x) SDL_assert(y); else + * do_something();` + * - It works the same everywhere, instead of counting on various platforms' + * compiler and C runtime to behave. + * - It provides multiple levels of assertion (SDL_assert, SDL_assert_release, + * SDL_assert_paranoid) instead of a single all-or-nothing option. + * - It offers a variety of responses when an assertion fails (retry, trigger + * the debugger, abort the program, ignore the failure once, ignore it for + * the rest of the program's run). + * - It tries to show the user a dialog by default, if possible, but the app + * can provide a callback to handle assertion failures however they like. + * - It lets failed assertions be retried. Perhaps you had a network failure + * and just want to retry the test after plugging your network cable back + * in? You can. + * - It lets the user ignore an assertion failure, if there's a harmless + * problem that one can continue past. + * - It lets the user mark an assertion as ignored for the rest of the + * program's run; if there's a harmless problem that keeps popping up. + * - It provides statistics and data on all failed assertions to the app. + * - It allows the default assertion handler to be controlled with environment + * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. + * + * To use it: compile a debug build and just sprinkle around tests to check + * your code! + */ + +#ifndef SDL_assert_h_ +#define SDL_assert_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The level of assertion aggressiveness. + * + * This value changes depending on compiler options and other preprocessor + * defines. + * + * It is currently one of the following values, but future SDL releases might + * add more: + * + * - 0: All SDL assertion macros are disabled. + * - 1: Release settings: SDL_assert disabled, SDL_assert_release enabled. + * - 2: Debug settings: SDL_assert and SDL_assert_release enabled. + * - 3: Paranoid settings: All SDL assertion macros enabled, including + * SDL_assert_paranoid. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors + +#elif !defined(SDL_ASSERT_LEVEL) +#ifdef SDL_DEFAULT_ASSERT_LEVEL +#define SDL_ASSERT_LEVEL SDL_DEFAULT_ASSERT_LEVEL +#elif defined(_DEBUG) || defined(DEBUG) || \ + (defined(__GNUC__) && !defined(__OPTIMIZE__)) +#define SDL_ASSERT_LEVEL 2 +#else +#define SDL_ASSERT_LEVEL 1 +#endif +#endif + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Attempt to tell an attached debugger to pause. + * + * This allows an app to programmatically halt ("break") the debugger as if it + * had hit a breakpoint, allowing the developer to examine program state, etc. + * + * This is a macro--not a function--so that the debugger breaks on the source + * code line that used SDL_TriggerBreakpoint and not in some random guts of + * SDL. SDL_assert uses this macro for the same reason. + * + * If the program is not running under a debugger, SDL_TriggerBreakpoint will + * likely terminate the app, possibly without warning. If the current platform + * isn't supported, this macro is left undefined. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner + +#elif defined(_MSC_VER) && _MSC_VER >= 1310 + /* Don't include intrin.h here because it contains C++ code */ + extern void __cdecl __debugbreak(void); + #define SDL_TriggerBreakpoint() __debugbreak() +#elif defined(_MSC_VER) && defined(_M_IX86) + #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } +#elif defined(ANDROID) + #include + #define SDL_TriggerBreakpoint() assert(0) +#elif SDL_HAS_BUILTIN(__builtin_debugtrap) + #define SDL_TriggerBreakpoint() __builtin_debugtrap() +#elif SDL_HAS_BUILTIN(__builtin_trap) + #define SDL_TriggerBreakpoint() __builtin_trap() +#elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) +#elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\n\t" ) +#elif ( defined(SDL_PLATFORM_APPLE) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */ + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) +#elif defined(SDL_PLATFORM_APPLE) && defined(__arm__) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" ) +#elif defined(_WIN32) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__arm64__) || defined(__aarch64__)) ) + #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #0xF000\n\t" ) +#elif defined(__GNUC__) || defined(__clang__) + #define SDL_TriggerBreakpoint() __builtin_trap() /* older gcc may not support SDL_HAS_BUILTIN(__builtin_trap) above */ +#elif defined(__386__) && defined(__WATCOMC__) + #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } +#elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) + #include + #define SDL_TriggerBreakpoint() raise(SIGTRAP) +#else + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ +#endif + +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_LINE __LINE__ + +/* +sizeof (x) makes the compiler still parse the expression even without +assertions enabled, so the code is always checked at compile time, but +doesn't actually generate code for it, so there are no side effects or +expensive checks at run time, just the constant size of what x WOULD be, +which presumably gets optimized out as unused. +This also solves the problem of... + + int somevalue = blah(); + SDL_assert(somevalue == 1); + +...which would cause compiles to complain that somevalue is unused if we +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.2.0. + */ +#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! */ +#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.2.0. + */ +#define SDL_disabled_assert(condition) \ + do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) + +/** + * Possible outcomes from a triggered assertion. + * + * When an enabled assertion triggers, it may call the assertion handler + * (possibly one provided by the app via SDL_SetAssertionHandler), which will + * return one of these values, possibly after asking the user. + * + * Then SDL will respond based on this outcome (loop around to retry the + * condition, try to break in a debugger, kill the program, or ignore the + * problem). + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AssertState +{ + SDL_ASSERTION_RETRY, /**< Retry the assert immediately. */ + SDL_ASSERTION_BREAK, /**< Make the debugger trigger a breakpoint. */ + SDL_ASSERTION_ABORT, /**< Terminate the program. */ + SDL_ASSERTION_IGNORE, /**< Ignore the assert. */ + SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */ +} SDL_AssertState; + +/** + * Information about an assertion failure. + * + * This structure is filled in with information about a triggered assertion, + * used by the assertion handler, then added to the assertion report. This is + * returned as a linked list from SDL_GetAssertionReport(). + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AssertData +{ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ + unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ + const char *condition; /**< A string of this assert's test code. */ + const char *filename; /**< The source file where this assert lives. */ + int linenum; /**< The line in `filename` where this assert lives. */ + const char *function; /**< The name of the function where this assert lives. */ + const struct SDL_AssertData *next; /**< next item in the linked list. */ +} SDL_AssertData; + +/** + * Never call this directly. + * + * Use the SDL_assert macros instead. + * + * \param data assert data structure. + * \param func function name. + * \param file file name. + * \param line line number. + * \returns assert state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, + const char *func, + const char *file, int line) SDL_ANALYZER_NORETURN; + + +#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.2.0. + */ +#define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() + +#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 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.2.0. + */ +#define SDL_enabled_assert(condition) \ + do { \ + while ( !(condition) ) { \ + static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \ + const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \ + if (sdl_assert_state == SDL_ASSERTION_RETRY) { \ + continue; /* go again. */ \ + } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \ + SDL_AssertBreakpoint(); \ + } \ + break; /* not retrying. */ \ + } \ + } while (SDL_NULL_WHILE_LOOP_CONDITION) + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * An assertion test that is normally performed only in debug builds. + * + * This macro is enabled when the SDL_ASSERT_LEVEL is >= 2, otherwise it is + * disabled. This is meant to only do these tests in debug builds, so they can + * tend to be more expensive, and they are meant to bring everything to a halt + * when they fail, with the programmer there to assess the problem. + * + * In short: you can sprinkle these around liberally and assume they will + * evaporate out of the build when building for end-users. + * + * When assertions are disabled, this wraps `condition` in a `sizeof` + * operator, which means any function calls and side effects will not run, but + * the compiler will not complain about any otherwise-unused variables that + * are only referenced in the assertion. + * + * One can set the environment variable "SDL_ASSERT" to one of several strings + * ("abort", "break", "retry", "ignore", "always_ignore") to force a default + * behavior, which may be desirable for automation purposes. If your platform + * requires GUI interfaces to happen on the main thread but you're debugging + * an assertion in a background thread, it might be desirable to set this to + * "break" so that your debugger takes control as soon as assert is triggered, + * instead of risking a bad UI interaction (deadlock, etc) in the application. + * + * \param condition boolean value to test. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } + +/** + * An assertion test that is performed even in release builds. + * + * This macro is enabled when the SDL_ASSERT_LEVEL is >= 1, otherwise it is + * disabled. This is meant to be for tests that are cheap to make and + * extremely unlikely to fail; generally it is frowned upon to have an + * assertion failure in a release build, so these assertions generally need to + * be of more than life-and-death importance if there's a chance they might + * trigger. You should almost always consider handling these cases more + * gracefully than an assert allows. + * + * When assertions are disabled, this wraps `condition` in a `sizeof` + * operator, which means any function calls and side effects will not run, but + * the compiler will not complain about any otherwise-unused variables that + * are only referenced in the assertion. + * + * One can set the environment variable "SDL_ASSERT" to one of several strings + * ("abort", "break", "retry", "ignore", "always_ignore") to force a default + * behavior, which may be desirable for automation purposes. If your platform + * requires GUI interfaces to happen on the main thread but you're debugging + * an assertion in a background thread, it might be desirable to set this to + * "break" so that your debugger takes control as soon as assert is triggered, + * instead of risking a bad UI interaction (deadlock, etc) in the application. + * * + * + * \param condition boolean value to test. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_assert_release(condition) SDL_disabled_assert(condition) + +/** + * An assertion test that is performed only when built with paranoid settings. + * + * This macro is enabled when the SDL_ASSERT_LEVEL is >= 3, otherwise it is + * disabled. This is a higher level than both release and debug, so these + * tests are meant to be expensive and only run when specifically looking for + * extremely unexpected failure cases in a special build. + * + * When assertions are disabled, this wraps `condition` in a `sizeof` + * operator, which means any function calls and side effects will not run, but + * the compiler will not complain about any otherwise-unused variables that + * are only referenced in the assertion. + * + * One can set the environment variable "SDL_ASSERT" to one of several strings + * ("abort", "break", "retry", "ignore", "always_ignore") to force a default + * behavior, which may be desirable for automation purposes. If your platform + * requires GUI interfaces to happen on the main thread but you're debugging + * an assertion in a background thread, it might be desirable to set this to + * "break" so that your debugger takes control as soon as assert is triggered, + * instead of risking a bad UI interaction (deadlock, etc) in the application. + * + * \param condition boolean value to test. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) + +/* Enable various levels of assertions. */ +#elif SDL_ASSERT_LEVEL == 0 /* assertions disabled */ +# define SDL_assert(condition) SDL_disabled_assert(condition) +# define SDL_assert_release(condition) SDL_disabled_assert(condition) +# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) +#elif SDL_ASSERT_LEVEL == 1 /* release settings. */ +# define SDL_assert(condition) SDL_disabled_assert(condition) +# define SDL_assert_release(condition) SDL_enabled_assert(condition) +# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) +#elif SDL_ASSERT_LEVEL == 2 /* debug settings. */ +# define SDL_assert(condition) SDL_enabled_assert(condition) +# define SDL_assert_release(condition) SDL_enabled_assert(condition) +# define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) +#elif SDL_ASSERT_LEVEL == 3 /* paranoid settings. */ +# define SDL_assert(condition) SDL_enabled_assert(condition) +# define SDL_assert_release(condition) SDL_enabled_assert(condition) +# define SDL_assert_paranoid(condition) SDL_enabled_assert(condition) +#else +# error Unknown assertion level. +#endif + +/** + * An assertion test that is always performed. + * + * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You + * almost never want to use this, as it could trigger on an end-user's system, + * crashing your program. + * + * One can set the environment variable "SDL_ASSERT" to one of several strings + * ("abort", "break", "retry", "ignore", "always_ignore") to force a default + * behavior, which may be desirable for automation purposes. If your platform + * requires GUI interfaces to happen on the main thread but you're debugging + * an assertion in a background thread, it might be desirable to set this to + * "break" so that your debugger takes control as soon as assert is triggered, + * instead of risking a bad UI interaction (deadlock, etc) in the application. + * + * \param condition boolean value to test. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_assert_always(condition) SDL_enabled_assert(condition) + + +/** + * A callback that fires when an SDL assertion fails. + * + * \param data a pointer to the SDL_AssertData structure corresponding to the + * current assertion. + * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). + * \returns an SDL_AssertState value indicating how to handle the failure. + * + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( + const SDL_AssertData *data, void *userdata); + +/** + * Set an application-defined assertion handler. + * + * This function allows an application to show its own assertion UI and/or + * force the response to an assertion failure. If the application doesn't + * provide this, SDL will try to do the right thing, popping up a + * system-specific GUI dialog, and probably minimizing any fullscreen windows. + * + * This callback may fire from any thread, but it runs wrapped in a mutex, so + * it will only fire from one thread at a time. + * + * This callback is NOT reset to SDL's internal handler upon SDL_Quit()! + * + * \param handler the SDL_AssertionHandler function to call when an assertion + * fails or NULL for the default handler. + * \param userdata a pointer that is passed to `handler`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAssertionHandler + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( + SDL_AssertionHandler handler, + void *userdata); + +/** + * Get the default assertion handler. + * + * This returns the function pointer that is called by default when an + * assertion is triggered. This is an internal function provided by SDL, that + * is used for assertions when SDL_SetAssertionHandler() hasn't been used to + * provide a different function. + * + * \returns the default SDL_AssertionHandler that is called when an assert + * triggers. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAssertionHandler + */ +extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void); + +/** + * Get the current assertion handler. + * + * This returns the function pointer that is called when an assertion is + * triggered. This is either the value last passed to + * SDL_SetAssertionHandler(), or if no application-specified function is set, + * is equivalent to calling SDL_GetDefaultAssertionHandler(). + * + * The parameter `puserdata` is a pointer to a void*, which will store the + * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value + * will always be NULL for the default handler. If you don't care about this + * data, it is safe to pass a NULL pointer to this function to ignore it. + * + * \param puserdata pointer which is filled with the "userdata" pointer that + * was passed to SDL_SetAssertionHandler(). + * \returns the SDL_AssertionHandler that is called when an assert triggers. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAssertionHandler + */ +extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata); + +/** + * Get a list of all assertion failures. + * + * This function gets all assertions triggered since the last call to + * SDL_ResetAssertionReport(), or the start of the program. + * + * The proper way to examine this data looks something like this: + * + * ```c + * const SDL_AssertData *item = SDL_GetAssertionReport(); + * while (item) { + * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n", + * item->condition, item->function, item->filename, + * item->linenum, item->trigger_count, + * item->always_ignore ? "yes" : "no"); + * item = item->next; + * } + * ``` + * + * \returns a list of all failed assertions or NULL if the list is empty. This + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). + * + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResetAssertionReport + */ +extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); + +/** + * Clear the list of all assertion failures. + * + * This function will clear the list of all assertions triggered up to that + * point. Immediately following this call, SDL_GetAssertionReport will return + * no items. In addition, any previously-triggered assertions will be reset to + * a trigger_count of zero, and their always_ignore state will be false. + * + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAssertionReport + */ +extern SDL_DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_assert_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_asyncio.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_asyncio.h new file mode 100644 index 0000000000..b36cb071bc --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_atomic.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_atomic.h new file mode 100644 index 0000000000..78b5e0fa5b --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_atomic.h @@ -0,0 +1,664 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryAtomic + * + * Atomic operations. + * + * IMPORTANT: If you are not an expert in concurrent lockless programming, you + * should not be using any functions in this file. You should be protecting + * your data structures with full mutexes instead. + * + * ***Seriously, here be dragons!*** + * + * You can find out a little more about lockless programming and the subtle + * issues that can arise here: + * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming + * + * There's also lots of good information here: + * + * - https://www.1024cores.net/home/lock-free-algorithms + * - https://preshing.com/ + * + * These operations may or may not actually be implemented using processor + * specific atomic operations. When possible they are implemented as true + * processor specific atomic operations. When that is not possible the are + * implemented using locks that *do* use the available atomic operations. + * + * All of the atomic operations that modify memory are full memory barriers. + */ + +#ifndef SDL_atomic_h_ +#define SDL_atomic_h_ + +#include +#include + +#include + +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An atomic spinlock. + * + * The atomic locks are efficient spinlocks using CPU instructions, but are + * vulnerable to starvation and can spin forever if a thread holding a lock + * has been terminated. For this reason you should minimize the code executed + * inside an atomic lock and never do expensive things like API or system + * calls while holding them. + * + * They are also vulnerable to starvation if the thread holding the lock is + * lower priority than other threads and doesn't get scheduled. In general you + * should use mutexes instead, since they have better performance and + * contention behavior. + * + * The atomic locks are not safe to lock recursively. + * + * Porting Note: The spin lock functions and type are required and can not be + * emulated because they are used in the atomic emulation code. + */ +typedef int SDL_SpinLock; + +/** + * Try to lock a spin lock by setting it to a non-zero value. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a pointer to a lock variable. + * \returns true if the lock succeeded, false if the lock is already held. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockSpinlock + * \sa SDL_UnlockSpinlock + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); + +/** + * Lock a spin lock by setting it to a non-zero value. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a pointer to a lock variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryLockSpinlock + * \sa SDL_UnlockSpinlock + */ +extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); + +/** + * Unlock a spin lock by setting it to 0. + * + * Always returns immediately. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a pointer to a lock variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockSpinlock + * \sa SDL_TryLockSpinlock + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Mark a compiler barrier. + * + * A compiler barrier prevents the compiler from reordering reads and writes + * to globally visible variables across the call. + * + * This macro only prevents the compiler from reordering reads and writes, it + * does not prevent the CPU from reordering reads and writes. However, all of + * the atomic operations that modify memory are full memory barriers. + * + * \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 macro is available since SDL 3.2.0. + */ +#define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + +#elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) +void _ReadWriteBarrier(void); +#pragma intrinsic(_ReadWriteBarrier) +#define SDL_CompilerBarrier() _ReadWriteBarrier() +#elif (defined(__GNUC__) && !defined(SDL_PLATFORM_EMSCRIPTEN)) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) +/* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */ +#define SDL_CompilerBarrier() __asm__ __volatile__ ("" : : : "memory") +#elif defined(__WATCOMC__) +extern __inline void SDL_CompilerBarrier(void); +#pragma aux SDL_CompilerBarrier = "" parm [] modify exact []; +#else +#define SDL_CompilerBarrier() \ +{ SDL_SpinLock _tmp = 0; SDL_LockSpinlock(&_tmp); SDL_UnlockSpinlock(&_tmp); } +#endif + +/** + * 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.2.0. + * + * \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.2.0. + * + * \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. + * + * A typical pattern would be for thread A to write some data and a flag, and + * for thread B to read the flag and get the data. In this case you would + * insert a release barrier between writing the data and the flag, + * guaranteeing that the data write completes no later than the flag is + * written, and you would insert an acquire barrier between reading the flag + * and reading the data, to ensure that all the reads associated with the flag + * have completed. + * + * In this pattern you should always see a release barrier paired with an + * acquire barrier and you should gate the data reads/writes with a single + * flag variable. + * + * 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 macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction + */ +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() + +/** + * Insert a memory acquire barrier (macro version). + * + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. + * + * 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 macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction + */ +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() + +#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__) +#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") +#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") +#elif defined(__GNUC__) && defined(__arm__) +#if 0 /* defined(SDL_PLATFORM_LINUX) || defined(SDL_PLATFORM_ANDROID) */ +/* Information from: + https://chromium.googlesource.com/chromium/chromium/+/trunk/base/atomicops_internals_arm_gcc.h#19 + + The Linux kernel provides a helper function which provides the right code for a memory barrier, + hard-coded at address 0xffff0fa0 +*/ +typedef void (*SDL_KernelMemoryBarrierFunc)(); +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#else +#if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) +#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") +#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") +#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) +#ifdef __thumb__ +/* The mcr instruction isn't available in thumb mode, use real functions */ +#define SDL_MEMORY_BARRIER_USES_FUNCTION +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() +#else +#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") +#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") +#endif /* __thumb__ */ +#else +#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("" : : : "memory") +#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("" : : : "memory") +#endif /* SDL_PLATFORM_LINUX || SDL_PLATFORM_ANDROID */ +#endif /* __GNUC__ && __arm__ */ +#else +#if (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) +/* This is correct for all CPUs on Solaris when using Solaris Studio 12.1+. */ +#include +#define SDL_MemoryBarrierRelease() __machine_rel_barrier() +#define SDL_MemoryBarrierAcquire() __machine_acq_barrier() +#else +/* This is correct for the x86 and x64 CPUs, and we'll expand this over time. */ +#define SDL_MemoryBarrierRelease() SDL_CompilerBarrier() +#define SDL_MemoryBarrierAcquire() SDL_CompilerBarrier() +#endif +#endif + +/* "REP NOP" is PAUSE, coded for tools that don't know it by that name. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to insert a CPU-specific "pause" instruction into the program. + * + * This can be useful in busy-wait loops, as it serves as a hint to the CPU as + * to the program's intent; some CPUs can use this to do more efficient + * processing. On some platforms, this doesn't do anything, so using this + * macro might just be a harmless no-op. + * + * Note that if you are busy-waiting, there are often more-efficient + * approaches with other synchronization primitives: mutexes, semaphores, + * condition variables, etc. + * + * \threadsafety This macro is safe to use from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#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__) + #define SDL_CPUPauseInstruction() __asm__ __volatile__("yield" ::: "memory") +#elif (defined(__powerpc__) || defined(__powerpc64__)) + #define SDL_CPUPauseInstruction() __asm__ __volatile__("or 27,27,27"); +#elif (defined(__riscv) && __riscv_xlen == 64) + #define SDL_CPUPauseInstruction() __asm__ __volatile__(".insn i 0x0F, 0, x0, x0, 0x010"); +#elif defined(_MSC_VER) && (defined(_M_IX86) || defined(_M_X64)) + #define SDL_CPUPauseInstruction() _mm_pause() /* this is actually "rep nop" and not a SIMD instruction. No inline asm in MSVC x86-64! */ +#elif defined(_MSC_VER) && (defined(_M_ARM) || defined(_M_ARM64)) + #define SDL_CPUPauseInstruction() __yield() +#elif defined(__WATCOMC__) && defined(__386__) + extern __inline void SDL_CPUPauseInstruction(void); + #pragma aux SDL_CPUPauseInstruction = ".686p" ".xmm2" "pause" +#else + #define SDL_CPUPauseInstruction() +#endif + + +/** + * A type representing an atomic integer value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt + */ +typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicInt variable to be modified. + * \param oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); + +/** + * Set an atomic variable to a value. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicInt variable to be modified. + * \param v the desired value. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicInt + */ +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); + +/** + * Get the value of an atomic variable. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicInt variable. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicInt + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); + +/** + * Add to an atomic variable. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicInt variable to be modified. + * \param v the desired value to add. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AtomicDecRef + * \sa SDL_AtomicIncRef + */ +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); + +#ifndef SDL_AtomicIncRef + +/** + * Increment an atomic variable used as a reference count. + * + * ***Note: If you don't know what this macro is for, you shouldn't use it!*** + * + * \param a a pointer to an SDL_AtomicInt to increment. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AtomicDecRef + */ +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) +#endif + +#ifndef SDL_AtomicDecRef + +/** + * Decrement an atomic variable used as a reference count. + * + * ***Note: If you don't know what this macro is for, you shouldn't use it!*** + * + * \param a a pointer to an SDL_AtomicInt to decrement. + * \returns true if the variable reached zero after decrementing, false + * otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AtomicIncRef + */ +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) +#endif + +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable to be modified. + * \param oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable to be modified. + * \param v the desired value. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + +/** + * Set a pointer to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to a pointer. + * \param oldval the old pointer value. + * \param newval the new pointer value. + * \returns true if the pointer was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); + +/** + * Set a pointer to a value atomically. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to a pointer. + * \param v the desired pointer value. + * \returns the previous value of the pointer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer + */ +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); + +/** + * Get the value of a pointer atomically. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to a pointer. + * \returns the current value of a pointer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif + +#include + +#endif /* SDL_atomic_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_audio.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_audio.h new file mode 100644 index 0000000000..ad2ece02ab --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_audio.h @@ -0,0 +1,2200 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryAudio + * + * Audio functionality for the SDL library. + * + * All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play + * or record audio, convert it, stream it, buffer it, or mix it, you're going + * to be passing it through an audio stream. + * + * Audio streams are quite flexible; they can accept any amount of data at a + * time, in any supported format, and output it as needed in any other format, + * even if the data format changes on either side halfway through. + * + * An app opens an audio device and binds any number of audio streams to it, + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. + * + * Audio streams can also use an app-provided callback to supply data + * on-demand, which maps pretty closely to the SDL2 audio model. + * + * SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO + * if you aren't reading from a file) as a basic means to load sound data into + * your program. + * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * + * ## Channel layouts + * + * Audio data passing through SDL is uncompressed PCM data, interleaved. One + * can provide their own decompression through an MP3, etc, decoder, but SDL + * does not provide this directly. Each interleaved channel of data is meant + * to be in a specific order. + * + * Abbreviations: + * + * - FRONT = single mono speaker + * - FL = front left speaker + * - FR = front right speaker + * - FC = front center speaker + * - BL = back left speaker + * - BR = back right speaker + * - SR = surround right speaker + * - SL = surround left speaker + * - BC = back center speaker + * - LFE = low-frequency speaker + * + * These are listed in the order they are laid out in memory, so "FL, FR" + * means "the front left speaker is laid out in memory first, then the front + * right, then it repeats for the next audio frame". + * + * - 1 channel (mono) layout: FRONT + * - 2 channels (stereo) layout: FL, FR + * - 3 channels (2.1) layout: FL, FR, LFE + * - 4 channels (quad) layout: FL, FR, BL, BR + * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR + * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be + * SL, SR) + * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR + * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR + * + * This is the same order as DirectSound expects, but applied to all + * platforms; SDL will swizzle the channels as necessary if a platform expects + * something different. + * + * SDL_AudioStream can also be provided channel maps to change this ordering + * to whatever is necessary, in other audio processing scenarios. + */ + +#ifndef SDL_audio_h_ +#define SDL_audio_h_ + +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * 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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_AUDIO_MASK_SIGNED (1u<<15) + +/** + * 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.2.0. + */ +#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. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_AUDIO_BITSIZE + * \sa SDL_AUDIO_BYTESIZE + * \sa SDL_AUDIO_ISINT + * \sa SDL_AUDIO_ISFLOAT + * \sa SDL_AUDIO_ISBIGENDIAN + * \sa SDL_AUDIO_ISLITTLEENDIAN + * \sa SDL_AUDIO_ISSIGNED + * \sa SDL_AUDIO_ISUNSIGNED + */ +typedef enum SDL_AudioFormat +{ + SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */ + SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */ + SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */ + SDL_AUDIO_S16LE = 0x8010u, /**< Signed 16-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */ + SDL_AUDIO_S16BE = 0x9010u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */ + SDL_AUDIO_S32LE = 0x8020u, /**< 32-bit integer samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */ + SDL_AUDIO_S32BE = 0x9020u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */ + SDL_AUDIO_F32LE = 0x8120u, /**< 32-bit floating point samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ + SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ + + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; + + +/** + * Retrieve the size, in bits, from an SDL_AudioFormat. + * + * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16. + * + * \param x an SDL_AudioFormat value. + * \returns data size in bits. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) + +/** + * Retrieve the size, in bytes, from an SDL_AudioFormat. + * + * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2. + * + * \param x an SDL_AudioFormat value. + * \returns data size in bytes. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) + +/** + * Determine if an SDL_AudioFormat represents floating point data. + * + * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is floating point, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) + +/** + * Determine if an SDL_AudioFormat represents bigendian data. + * + * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is bigendian, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) + +/** + * Determine if an SDL_AudioFormat represents littleendian data. + * + * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is littleendian, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) + +/** + * Determine if an SDL_AudioFormat represents signed data. + * + * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is signed, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) + +/** + * Determine if an SDL_AudioFormat represents integer data. + * + * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is integer, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) + +/** + * Determine if an SDL_AudioFormat represents unsigned data. + * + * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0. + * + * \param x an SDL_AudioFormat value. + * \returns non-zero if format is unsigned, zero otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) + + +/** + * SDL Audio Device instance IDs. + * + * Zero is used to signify an invalid/null device. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_AudioDeviceID; + +/** + * A value used to request a default playback audio device. + * + * Several functions that require an SDL_AudioDeviceID will accept this value + * to signify the app just wants the system to choose a default device instead + * of the app providing a specific one. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) + +/** + * A value used to request a default recording audio device. + * + * Several functions that require an SDL_AudioDeviceID will accept this value + * to signify the app just wants the system to choose a default device instead + * of the app providing a specific one. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) + +/** + * Format specifier for audio data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AudioFormat + */ +typedef struct SDL_AudioSpec +{ + SDL_AudioFormat format; /**< Audio data format */ + int channels; /**< Number of channels: 1 mono, 2 stereo, etc */ + int freq; /**< sample rate: sample frames per second */ +} SDL_AudioSpec; + +/** + * Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec. + * + * This reports on the size of an audio sample frame: stereo Sint16 data (2 + * channels of 2 bytes each) would be 4 bytes per frame, for example. + * + * \param x an SDL_AudioSpec to query. + * \returns the number of bytes used per sample frame. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) + +/** + * The opaque handle that represents an audio stream. + * + * SDL_AudioStream is an audio conversion interface. + * + * - It can handle resampling data in chunks without generating artifacts, + * when it doesn't have the complete buffer available. + * - It can handle incoming data in any variable size. + * - It can handle input/output format changes on the fly. + * - It can remap audio channels between inputs and outputs. + * - You push data as you have it, and pull it when you need it + * - It can also function as a basic audio data queue even if you just have + * sound that needs to pass from one place to another. + * - You can hook callbacks up to them when more data is added or requested, + * to manage data on-the-fly. + * + * Audio streams are the core of the SDL3 audio interface. You create one or + * more of them, bind them to an opened audio device, and feed data to them + * (or for recording, consume data from them). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAudioStream + */ +typedef struct SDL_AudioStream SDL_AudioStream; + + +/* Function prototypes */ + +/** + * Use this function to get the number of built-in audio drivers. + * + * This function returns a hardcoded number. This never returns a negative + * value; if there are no drivers compiled into this build of SDL, this + * function returns zero. The presence of a driver in this list does not mean + * it will function, it just means SDL is capable of interacting with that + * interface. For example, a build of SDL might have esound support, but if + * there's no esound server available, SDL's esound driver would fail if used. + * + * By default, SDL tries all drivers, in its preferred order, until one is + * found to be usable. + * + * \returns the number of built-in audio drivers. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); + +/** + * Use this function to get the name of a built in audio driver. + * + * The list of audio drivers is given in the order that they are normally + * initialized by default; the drivers that seem more reasonable to choose + * first (as far as the SDL developers believe) are earlier in the list. + * + * The names of drivers are all simple, low-ASCII identifiers, like "alsa", + * "coreaudio" or "wasapi". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of the audio driver; the value ranges from 0 to + * SDL_GetNumAudioDrivers() - 1. + * \returns the name of the audio driver at the requested index, or NULL if an + * invalid index was specified. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumAudioDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); + +/** + * Get the name of the current audio driver. + * + * The names of drivers are all simple, low-ASCII identifiers, like "alsa", + * "coreaudio" or "wasapi". These never have Unicode characters, and are not + * meant to be proper names. + * + * \returns the name of the current audio driver or NULL if no driver has been + * initialized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); + +/** + * Get a list of currently-connected audio playback devices. + * + * This returns of list of available devices that play sound, perhaps to + * speakers or headphones ("playback" devices). If you want devices that + * record audio, like a microphone ("recording" devices), use + * SDL_GetAudioRecordingDevices() instead. + * + * This only returns a list of physical devices; it will not have any device + * IDs returned by SDL_OpenAudioDevice(). + * + * If this function returns NULL, to signify an error, `*count` will be set to + * zero. + * + * \param count a pointer filled in with the number of devices returned, may + * be NULL. + * \returns a 0 terminated array of device instance IDs or NULL on error; call + * SDL_GetError() for more information. This should be freed with + * SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenAudioDevice + * \sa SDL_GetAudioRecordingDevices + */ +extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count); + +/** + * Get a list of currently-connected audio recording devices. + * + * This returns of list of available devices that record audio, like a + * microphone ("recording" devices). If you want devices that play sound, + * perhaps to speakers or headphones ("playback" devices), use + * SDL_GetAudioPlaybackDevices() instead. + * + * This only returns a list of physical devices; it will not have any device + * IDs returned by SDL_OpenAudioDevice(). + * + * If this function returns NULL, to signify an error, `*count` will be set to + * zero. + * + * \param count a pointer filled in with the number of devices returned, may + * be NULL. + * \returns a 0 terminated array of device instance IDs, or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenAudioDevice + * \sa SDL_GetAudioPlaybackDevices + */ +extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count); + +/** + * Get the human-readable name of a specific audio device. + * + * \param devid the instance ID of the device to query. + * \returns the name of the audio device, or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioPlaybackDevices + * \sa SDL_GetAudioRecordingDevices + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); + +/** + * Get the current audio format of a specific audio device. + * + * For an opened device, this will report the format the device is currently + * using. If the device isn't yet opened, this will report the device's + * preferred format (or a reasonable default if this can't be determined). + * + * You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or + * SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a + * reasonable recommendation before opening the system-recommended default + * device. + * + * You can also use this to request the current device buffer size. This is + * specified in sample frames and represents the amount of data SDL will feed + * to the physical hardware in each chunk. This can be converted to + * milliseconds of audio with the following equation: + * + * `ms = (int) ((((Sint64) frames) * 1000) / spec.freq);` + * + * Buffer size is only important if you need low-level control over the audio + * playback timing. Most apps do not need this. + * + * \param devid the instance ID of the device to query. + * \param spec on return, will be filled with device details. + * \param sample_frames pointer to store device buffer size, in sample frames. + * Can be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); + +/** + * Get the current channel map of an audio device. + * + * Channel maps are optional; most things do not need them, instead passing + * data in the [order that SDL expects](CategoryAudio#channel-layouts). + * + * Audio devices usually have no remapping applied. This is represented by + * returning NULL, and does not signify an error. + * + * \param devid the instance ID of the device to query. + * \param count On output, set to number of channels in the map. Can be NULL. + * \returns an array of the current channel mapping, with as many elements as + * the current output spec's channels, or NULL if default. This + * should be freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamInputChannelMap + */ +extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count); + +/** + * Open a specific audio device. + * + * You can open both playback and recording devices through this function. + * Playback devices will take data from bound audio streams, mix it, and send + * it to the hardware. Recording devices will feed any bound audio streams + * with a copy of any incoming data. + * + * An opened audio device starts out with no audio streams bound. To start + * audio playing, bind a stream and supply audio data to it. Unlike SDL2, + * there is no audio callback; you only bind audio streams and make sure they + * have data flowing into them (however, you can simulate SDL2's semantics + * fairly closely by using SDL_OpenAudioDeviceStream instead of this + * function). + * + * If you don't care about opening a specific device, pass a `devid` of either + * `SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK` or + * `SDL_AUDIO_DEVICE_DEFAULT_RECORDING`. In this case, SDL will try to pick + * the most reasonable default, and may also switch between physical devices + * seamlessly later, if the most reasonable default changes during the + * lifetime of this opened device (user changed the default in the OS's system + * preferences, the default got unplugged so the system jumped to a new + * default, the user plugged in headphones on a mobile device, etc). Unless + * you have a good reason to choose a specific device, this is probably what + * you want. + * + * You may request a specific format for the audio device, but there is no + * promise the device will honor that request for several reasons. As such, + * it's only meant to be a hint as to what data your app will provide. Audio + * streams will accept data in whatever format you specify and manage + * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you + * the preferred format for the device before opening and the actual format + * the device is using after opening. + * + * It's legal to open the same device ID more than once; each successful open + * will generate a new logical SDL_AudioDeviceID that is managed separately + * from others on the same physical device. This allows libraries to open a + * device separately from the main app and bind its own streams without + * conflicting. + * + * It is also legal to open a device ID returned by a previous call to this + * function; doing so just creates another logical device on the same physical + * device. This may be useful for making logical groupings of audio streams. + * + * This function returns the opened device ID on success. This is a new, + * unique SDL_AudioDeviceID that represents a logical device. + * + * Some backends might offer arbitrary devices (for example, a networked audio + * protocol that can connect to an arbitrary server). For these, as a change + * from SDL2, you should open a default device ID and use an SDL hint to + * specify the target if you care, or otherwise let the backend figure out a + * reasonable default. Most backends don't offer anything like this, and often + * this would be an end user setting an environment variable for their custom + * need, and not something an application should specifically manage. + * + * When done with an audio device, possibly at the end of the app's life, one + * should call SDL_CloseAudioDevice() on the returned device id. + * + * \param devid the device instance id to open, or + * SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or + * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable + * default device. + * \param spec the requested device configuration. Can be NULL to use + * reasonable defaults. + * \returns the device ID on success or 0 on failure; call SDL_GetError() for + * more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAudioDevice + * \sa SDL_GetAudioDeviceFormat + */ +extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); + +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + +/** + * Use this function to pause audio playback on a specified device. + * + * This function pauses audio processing for a given device. Any bound audio + * streams will not progress, and no audio will be generated. Pausing one + * device does not prevent other unpaused devices from running. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. Pausing a paused device is + * a legal no-op. + * + * Pausing a device can be useful to halt all audio without unbinding all the + * audio streams. This might be useful while a game is paused, or a level is + * loading, etc. + * + * Physical devices can not be paused or unpaused, only logical devices + * created through SDL_OpenAudioDevice() can be. + * + * \param devid a device opened by SDL_OpenAudioDevice(). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResumeAudioDevice + * \sa SDL_AudioDevicePaused + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID devid); + +/** + * Use this function to unpause audio playback on a specified device. + * + * This function unpauses audio processing for a given device that has + * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any + * bound audio streams will begin to progress again, and audio can be + * generated. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. Unpausing an unpaused + * device is a legal no-op. + * + * Physical devices can not be paused or unpaused, only logical devices + * created through SDL_OpenAudioDevice() can be. + * + * \param devid a device opened by SDL_OpenAudioDevice(). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AudioDevicePaused + * \sa SDL_PauseAudioDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID devid); + +/** + * Use this function to query if an audio device is paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * Physical devices can not be paused or unpaused, only logical devices + * created through SDL_OpenAudioDevice() can be. Physical and invalid device + * IDs will report themselves as unpaused here. + * + * \param devid a device opened by SDL_OpenAudioDevice(). + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioDevice + * \sa SDL_ResumeAudioDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID devid); + +/** + * Get the gain of an audio device. + * + * The gain of a device is its volume; a larger gain means a louder output, + * with a gain of zero being silence. + * + * Audio devices default to a gain of 1.0f (no change in output). + * + * Physical devices may not have their gain changed, only logical devices, and + * this function will always return -1.0f when used on physical devices. + * + * \param devid the audio device to query. + * \returns the gain of the device or -1.0f on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioDeviceGain + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid); + +/** + * Change the gain of an audio device. + * + * The gain of a device is its volume; a larger gain means a louder output, + * with a gain of zero being silence. + * + * Audio devices default to a gain of 1.0f (no change in output). + * + * Physical devices may not have their gain changed, only logical devices, and + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this + * way, it would allow an app or library to interfere with another portion of + * the program's otherwise-isolated devices. + * + * This is applied, along with any per-audiostream gain, during playback to + * the hardware, and can be continuously changed to create various effects. On + * recording devices, this will adjust the gain before passing the data into + * an audiostream; that recording audiostream can then adjust its gain further + * when outputting the data elsewhere, if it likes, but that second gain is + * not applied until the data leaves the audiostream again. + * + * \param devid the audio device on which to change gain. + * \param gain the gain. 1.0f is no change, 0.0f is silence. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioDeviceGain + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); + +/** + * Close a previously-opened audio device. + * + * The application should close open audio devices once they are no longer + * needed. + * + * This function may block briefly while pending audio data is played by the + * hardware, so that applications don't drop the last buffer of data they + * supplied if terminating immediately afterwards. + * + * \param devid an audio device id previously returned by + * SDL_OpenAudioDevice(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenAudioDevice + */ +extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); + +/** + * Bind a list of audio streams to an audio device. + * + * Audio data will flow through any bound streams. For a playback device, data + * for all bound streams will be mixed together and fed to the device. For a + * recording device, a copy of recorded data will be provided to each bound + * stream. + * + * Audio streams can only be bound to an open device. This operation is + * atomic--all streams bound in the same call will start processing at the + * same time, so they can stay in sync. Also: either all streams will be bound + * or none of them will be. + * + * It is an error to bind an already-bound stream; it must be explicitly + * unbound first. + * + * Binding a stream to a device will set its output format for playback + * devices, and its input format for recording devices, so they match the + * device's settings. The caller is welcome to change the other end of the + * stream's format at any time with SDL_SetAudioStreamFormat(). + * + * \param devid an audio device to bind a stream to. + * \param streams an array of audio streams to bind. + * \param num_streams number streams listed in the `streams` array. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindAudioStreams + * \sa SDL_UnbindAudioStream + * \sa SDL_GetAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); + +/** + * Bind a single audio stream to an audio device. + * + * This is a convenience function, equivalent to calling + * `SDL_BindAudioStreams(devid, &stream, 1)`. + * + * \param devid an audio device to bind a stream to. + * \param stream an audio stream to bind to a device. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindAudioStreams + * \sa SDL_UnbindAudioStream + * \sa SDL_GetAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); + +/** + * Unbind a list of audio streams from their audio devices. + * + * The streams being unbound do not all have to be on the same device. All + * streams on the same device will be unbound atomically (data will stop + * flowing through all unbound streams on the same device at the same time). + * + * Unbinding a stream that isn't bound to a device is a legal no-op. + * + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. + * \param num_streams number streams listed in the `streams` array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindAudioStreams + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); + +/** + * Unbind a single audio stream from its audio device. + * + * This is a convenience function, equivalent to calling + * `SDL_UnbindAudioStreams(&stream, 1)`. + * + * \param stream an audio stream to unbind from a device. Can be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindAudioStream + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); + +/** + * Query an audio stream for its currently-bound device. + * + * This reports the logical audio device that an audio stream is currently bound to. + * + * If not bound, or invalid, this returns zero, which is not a valid device + * ID. + * + * \param stream the audio stream to query. + * \returns the bound audio device, or 0 if not bound or invalid. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindAudioStream + * \sa SDL_BindAudioStreams + */ +extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Create a new audio stream. + * + * \param src_spec the format details of the input audio. + * \param dst_spec the format details of the output audio. + * \returns a new audio stream on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PutAudioStreamData + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamAvailable + * \sa SDL_FlushAudioStream + * \sa SDL_ClearAudioStream + * \sa SDL_SetAudioStreamFormat + * \sa SDL_DestroyAudioStream + */ +extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); + +/** + * Get the properties associated with an audio stream. + * + * \param stream the SDL_AudioStream to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); + +/** + * Query the current format of an audio stream. + * + * \param stream the SDL_AudioStream to query. + * \param src_spec where to store the input audio format; ignored if NULL. + * \param dst_spec where to store the output audio format; ignored if NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamFormat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); + +/** + * Change the input and output formats of an audio stream. + * + * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData + * will reflect the new format, and future calls to SDL_PutAudioStreamData + * must provide data in the new input formats. + * + * Data that was previously queued in the stream will still be operated on in + * the format that was current when it was added, which is to say you can put + * the end of a sound file in one format to a stream, change formats for the + * next sound file, and start putting that new data while the previous sound + * file is still queued, and everything will still play back correctly. + * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * + * \param stream the stream the format is being changed. + * \param src_spec the new format of the audio input; if NULL, it is not + * changed. + * \param dst_spec the new format of the audio output; if NULL, it is not + * changed. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamFormat + * \sa SDL_SetAudioStreamFrequencyRatio + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); + +/** + * Get the frequency ratio of an audio stream. + * + * \param stream the SDL_AudioStream to query. + * \returns the frequency ratio of the stream or 0.0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamFrequencyRatio + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream); + +/** + * Change the frequency ratio of an audio stream. + * + * The frequency ratio is used to adjust the rate at which input data is + * consumed. Changing this effectively modifies the speed and pitch of the + * audio. A value greater than 1.0 will play the audio faster, and at a higher + * pitch. A value less than 1.0 will play the audio slower, and at a lower + * pitch. + * + * This is applied during SDL_GetAudioStreamData, and can be continuously + * changed to create various effects. + * + * \param stream the stream the frequency ratio is being changed. + * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 + * and 100. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamFrequencyRatio + * \sa SDL_SetAudioStreamFormat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); + +/** + * Get the gain of an audio stream. + * + * The gain of a stream is its volume; a larger gain means a louder output, + * with a gain of zero being silence. + * + * Audio streams default to a gain of 1.0f (no change in output). + * + * \param stream the SDL_AudioStream to query. + * \returns the gain of the stream or -1.0f on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamGain + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream); + +/** + * Change the gain of an audio stream. + * + * The gain of a stream is its volume; a larger gain means a louder output, + * with a gain of zero being silence. + * + * Audio streams default to a gain of 1.0f (no change in output). + * + * This is applied during SDL_GetAudioStreamData, and can be continuously + * changed to create various effects. + * + * \param stream the stream on which the gain is being changed. + * \param gain the gain. 1.0f is no change, 0.0f is silence. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamGain + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); + +/** + * Get the current input channel map of an audio stream. + * + * Channel maps are optional; most things do not need them, instead passing + * data in the [order that SDL expects](CategoryAudio#channel-layouts). + * + * Audio streams default to no remapping applied. This is represented by + * returning NULL, and does not signify an error. + * + * \param stream the SDL_AudioStream to query. + * \param count On output, set to number of channels in the map. Can be NULL. + * \returns an array of the current channel mapping, with as many elements as + * the current output spec's channels, or NULL if default. This + * should be freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamInputChannelMap + */ +extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count); + +/** + * Get the current output channel map of an audio stream. + * + * Channel maps are optional; most things do not need them, instead passing + * data in the [order that SDL expects](CategoryAudio#channel-layouts). + * + * Audio streams default to no remapping applied. This is represented by + * returning NULL, and does not signify an error. + * + * \param stream the SDL_AudioStream to query. + * \param count On output, set to number of channels in the map. Can be NULL. + * \returns an array of the current channel mapping, with as many elements as + * the current output spec's channels, or NULL if default. This + * should be freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamInputChannelMap + */ +extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count); + +/** + * Set the current input channel map of an audio stream. + * + * Channel maps are optional; most things do not need them, instead passing + * data in the [order that SDL expects](CategoryAudio#channel-layouts). + * + * The input channel map reorders data that is added to a stream via + * SDL_PutAudioStreamData. Future calls to SDL_PutAudioStreamData must provide + * data in the new channel order. + * + * Each item in the array represents an input channel, and its value is the + * channel that it should be remapped to. To reverse a stereo signal's left + * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap + * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. + * + * Data that was previously queued in the stream will still be operated on in + * the order that was current when it was added, which is to say you can put + * the end of a sound file in one order to a stream, change orders for the + * next sound file, and start putting that new data while the previous sound + * file is still queued, and everything will still play back correctly. + * + * Audio streams default to no remapping applied. Passing a NULL channel map + * is legal, and turns off remapping. + * + * SDL will copy the channel map; the caller does not have to save this array + * after this call. + * + * If `count` is not equal to the current number of channels in the audio + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the + * channel map. + * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * + * \param stream the SDL_AudioStream to change. + * \param chmap the new channel map, NULL to reset to default. + * \param count The number of channels in the map. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. Don't change the + * stream's format to have a different number of channels from a + * a different thread at the same time, though! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamInputChannelMap + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); + +/** + * Set the current output channel map of an audio stream. + * + * Channel maps are optional; most things do not need them, instead passing + * data in the [order that SDL expects](CategoryAudio#channel-layouts). + * + * The output channel map reorders data that leaving a stream via + * SDL_GetAudioStreamData. + * + * Each item in the array represents an input channel, and its value is the + * channel that it should be remapped to. To reverse a stereo signal's left + * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap + * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. + * + * The output channel map can be changed at any time, as output remapping is + * applied during SDL_GetAudioStreamData. + * + * Audio streams default to no remapping applied. Passing a NULL channel map + * is legal, and turns off remapping. + * + * SDL will copy the channel map; the caller does not have to save this array + * after this call. + * + * If `count` is not equal to the current number of channels in the audio + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the + * channel map. + * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * + * \param stream the SDL_AudioStream to change. + * \param chmap the new channel map, NULL to reset to default. + * \param count The number of channels in the map. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. Don't change the + * stream's format to have a different number of channels from a + * a different thread at the same time, though! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamInputChannelMap + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); + +/** + * Add data to the stream. + * + * This data must match the format/channels/samplerate specified in the latest + * call to SDL_SetAudioStreamFormat, or the format specified when creating the + * stream if it hasn't been changed. + * + * Note that this call simply copies the unconverted data for later. This is + * different than SDL2, where data was converted during the Put call and the + * Get call would just dequeue the previously-converted data. + * + * \param stream the stream the audio data is being added to. + * \param buf a pointer to the audio data to add. + * \param len the number of bytes to write to the stream. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but if the + * stream has a callback set, the caller might need to manage + * extra locking. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearAudioStream + * \sa SDL_FlushAudioStream + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamQueued + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); + +/** + * Get converted/resampled data from the stream. + * + * The input/output data format/channels/samplerate is specified when creating + * the stream, and can be changed after creation by calling + * SDL_SetAudioStreamFormat. + * + * Note that any conversion and resampling necessary is done during this call, + * and SDL_PutAudioStreamData simply queues unconverted data for later. This + * is different than SDL2, where that work was done while inputting new data + * to the stream and requesting the output just copied the converted data. + * + * \param stream the stream the audio is being requested from. + * \param buf a buffer to fill with audio data. + * \param len the maximum number of bytes to fill. + * \returns the number of bytes read from the stream or -1 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread, but if the + * stream has a callback set, the caller might need to manage + * extra locking. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearAudioStream + * \sa SDL_GetAudioStreamAvailable + * \sa SDL_PutAudioStreamData + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len); + +/** + * Get the number of converted/resampled bytes available. + * + * The stream may be buffering data behind the scenes until it has enough to + * resample correctly, so this number might be lower than what you expect, or + * even be zero. Add more data or flush the stream if you need the data now. + * + * If the stream has so much data that it would overflow an int, the return + * value is clamped to a maximum value, but no queued data is lost; if there + * are gigabytes of data queued, the app might need to read some of it with + * SDL_GetAudioStreamData before this function's return value is no longer + * clamped. + * + * \param stream the audio stream to query. + * \returns the number of converted/resampled bytes available or -1 on + * failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamData + * \sa SDL_PutAudioStreamData + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream); + + +/** + * Get the number of bytes currently queued. + * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * + * Note that audio streams can change their input format at any time, even if + * there is still data queued in a different format, so the returned byte + * count will not necessarily match the number of _sample frames_ available. + * Users of this API should be aware of format changes they make when feeding + * a stream and plan accordingly. + * + * Queued data is not converted until it is consumed by + * SDL_GetAudioStreamData, so this value should be representative of the exact + * data that was put into the stream. + * + * If the stream has so much data that it would overflow an int, the return + * value is clamped to a maximum value, but no queued data is lost; if there + * are gigabytes of data queued, the app might need to read some of it with + * SDL_GetAudioStreamData before this function's return value is no longer + * clamped. + * + * \param stream the audio stream to query. + * \returns the number of bytes queued or -1 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PutAudioStreamData + * \sa SDL_ClearAudioStream + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream); + + +/** + * Tell the stream that you're done sending data, and anything being buffered + * should be converted/resampled and made available immediately. + * + * It is legal to add more data to a stream after flushing, but there may be + * audio gaps in the output. Generally this is intended to signal the end of + * input, so the complete output becomes available. + * + * \param stream the audio stream to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PutAudioStreamData + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); + +/** + * Clear any pending data in the stream. + * + * This drops any queued data, so there will be nothing to read from the + * stream until more is added. + * + * \param stream the audio stream to clear. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamAvailable + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamQueued + * \sa SDL_PutAudioStreamData + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); + +/** + * Use this function to pause audio playback on the audio device associated + * with an audio stream. + * + * This function pauses audio processing for a given device. Any bound audio + * streams will not progress, and no audio will be generated. Pausing one + * device does not prevent other unpaused devices from running. + * + * Pausing a device can be useful to halt all audio without unbinding all the + * audio streams. This might be useful while a game is paused, or a level is + * loading, etc. + * + * \param stream the audio stream associated with the audio device to pause. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to unpause audio playback on the audio device associated + * with an audio stream. + * + * This function unpauses audio processing for a given device that has + * previously been paused. Once unpaused, any bound audio streams will begin + * to progress again, and audio can be generated. + * + * Remember, SDL_OpenAudioDeviceStream opens device in a paused state, so this + * function call is required for audio playback to begin on such device. + * + * \param stream the audio stream associated with the audio device to resume. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + + +/** + * Lock an audio stream for serialized access. + * + * Each SDL_AudioStream has an internal mutex it uses to protect its data + * structures from threading conflicts. This function allows an app to lock + * that mutex, which could be useful if registering callbacks on this stream. + * + * One does not need to lock a stream to use in it most cases, as the stream + * manages this lock internally. However, this lock is held during callbacks, + * which may run from arbitrary threads at any time, so if an app needs to + * protect shared data during those callbacks, locking the stream guarantees + * that the callback is not running while the lock is held. + * + * As this is just a wrapper over SDL_LockMutex for an internal lock; it has + * all the same attributes (recursive locks are allowed, etc). + * + * \param stream the audio stream to lock. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnlockAudioStream + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); + + +/** + * Unlock an audio stream for serialized access. + * + * This unlocks an audio stream after a call to SDL_LockAudioStream. + * + * \param stream the audio stream to unlock. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You should only call this from the same thread that + * previously called SDL_LockAudioStream. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockAudioStream + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); + +/** + * A callback that fires when data passes through an SDL_AudioStream. + * + * Apps can (optionally) register a callback with an audio stream that is + * called when data is added with SDL_PutAudioStreamData, or requested with + * SDL_GetAudioStreamData. + * + * Two values are offered here: one is the amount of additional data needed to + * satisfy the immediate request (which might be zero if the stream already + * has enough data queued) and the other is the total amount being requested. + * In a Get call triggering a Put callback, these values can be different. In + * a Put call triggering a Get callback, these values are always the same. + * + * Byte counts might be slightly overestimated due to buffering or resampling, + * and may change from call to call. + * + * This callback is not required to do anything. Generally this is useful for + * adding/reading data on demand, and the app will often put/get data as + * appropriate, but the system goes on with the data currently available to it + * if this callback does nothing. + * + * \param stream the SDL audio stream associated with this callback. + * \param additional_amount the amount of data, in bytes, that is needed right + * now. + * \param total_amount the total amount of data requested, in bytes, that is + * requested or available. + * \param userdata an opaque pointer provided by the app for their personal + * use. + * + * \threadsafety This callbacks may run from any thread, so if you need to + * protect shared data, you should use SDL_LockAudioStream to + * serialize access; this lock will be held before your callback + * is called, so your callback does not need to manage the lock + * explicitly. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamGetCallback + * \sa SDL_SetAudioStreamPutCallback + */ +typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount); + +/** + * Set a callback that runs when data is requested from an audio stream. + * + * This callback is called _before_ data is obtained from the stream, giving + * the callback the chance to add more on-demand. + * + * The callback can (optionally) call SDL_PutAudioStreamData() to add more + * audio to the stream during this call; if needed, the request that triggered + * this callback will obtain the new data immediately. + * + * The callback's `additional_amount` argument is roughly how many bytes of + * _unconverted_ data (in the stream's input format) is needed by the caller, + * although this may overestimate a little for safety. This takes into account + * how much is already in the stream and only asks for any extra necessary to + * resolve the request, which means the callback may be asked for zero bytes, + * and a different amount on each call. + * + * The callback is not required to supply exact amounts; it is allowed to + * supply too much or too little or none at all. The caller will get what's + * available, up to the amount they requested, regardless of this callback's + * outcome. + * + * Clearing or flushing an audio stream does not call this callback. + * + * This function obtains the stream's lock, which means any existing callback + * (get or put) in progress will finish running before setting the new + * callback. + * + * Setting a NULL function turns off the callback. + * + * \param stream the audio stream to set the new callback on. + * \param callback the new callback function to call when data is requested + * from the stream. + * \param userdata an opaque pointer provided to the callback for its own + * personal use. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamPutCallback + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); + +/** + * Set a callback that runs when data is added to an audio stream. + * + * This callback is called _after_ the data is added to the stream, giving the + * callback the chance to obtain it immediately. + * + * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio + * from the stream during this call. + * + * The callback's `additional_amount` argument is how many bytes of + * _converted_ data (in the stream's output format) was provided by the + * caller, although this may underestimate a little for safety. This value + * might be less than what is currently available in the stream, if data was + * already there, and might be less than the caller provided if the stream + * needs to keep a buffer to aid in resampling. Which means the callback may + * be provided with zero bytes, and a different amount on each call. + * + * The callback may call SDL_GetAudioStreamAvailable to see the total amount + * currently available to read from the stream, instead of the total provided + * by the current call. + * + * The callback is not required to obtain all data. It is allowed to read less + * or none at all. Anything not read now simply remains in the stream for + * later access. + * + * Clearing or flushing an audio stream does not call this callback. + * + * This function obtains the stream's lock, which means any existing callback + * (get or put) in progress will finish running before setting the new + * callback. + * + * Setting a NULL function turns off the callback. + * + * \param stream the audio stream to set the new callback on. + * \param callback the new callback function to call when data is added to the + * stream. + * \param userdata an opaque pointer provided to the callback for its own + * personal use. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamGetCallback + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); + + +/** + * Free an audio stream. + * + * This will release all allocated data, including any audio that is still + * queued. You do not need to manually clear the stream first. + * + * If this stream was bound to an audio device, it is unbound during this + * call. If this stream was created with SDL_OpenAudioDeviceStream, the audio + * device that was opened alongside this stream's creation will be closed, + * too. + * + * \param stream the audio stream to destroy. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateAudioStream + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream); + + +/** + * Convenience function for straightforward audio init for the common case. + * + * If all your app intends to do is provide a single source of PCM audio, this + * function allows you to do all your audio setup in a single call. + * + * This is also intended to be a clean means to migrate apps from SDL2. + * + * This function will open an audio device, create a stream and bind it. + * Unlike other methods of setup, the audio device will be closed when this + * stream is destroyed, so the app can treat the returned SDL_AudioStream as + * the only object needed to manage audio playback. + * + * Also unlike other functions, the audio device begins paused. This is to map + * more closely to SDL2-style behavior, since there is no extra step here to + * bind a stream to begin audio flowing. The audio device should be resumed + * with `SDL_ResumeAudioStreamDevice(stream);` + * + * This function works with both playback and recording devices. + * + * The `spec` parameter represents the app's side of the audio stream. That + * is, for recording audio, this will be the output format, and for playing + * audio, this will be the input format. If spec is NULL, the system will + * choose the format, and the app can use SDL_GetAudioStreamFormat() to obtain + * this information later. + * + * If you don't care about opening a specific audio device, you can (and + * probably _should_), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and + * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording. + * + * One can optionally provide a callback function; if NULL, the app is + * expected to queue audio data for playback (or unqueue audio data if + * capturing). Otherwise, the callback will begin to fire once the device is + * unpaused. + * + * Destroying the returned stream with SDL_DestroyAudioStream will also close + * the audio device associated with this stream. + * + * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK + * or SDL_AUDIO_DEVICE_DEFAULT_RECORDING. + * \param spec the audio stream's data format. Can be NULL. + * \param callback a callback where the app will provide new data for + * playback, or receive new data for recording. Can be NULL, + * in which case the app will need to call + * SDL_PutAudioStreamData or SDL_GetAudioStreamData as + * necessary. + * \param userdata app-controlled pointer passed to callback. Can be NULL. + * Ignored if callback is NULL. + * \returns an audio stream on success, ready to use, or NULL on failure; call + * SDL_GetError() for more information. When done with this stream, + * call SDL_DestroyAudioStream to free resources and close the + * device. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata); + +/** + * A callback that fires when data is about to be fed to an audio device. + * + * This is useful for accessing the final mix, perhaps for writing a + * visualizer or applying a final effect to the audio data before playback. + * + * This callback should run as quickly as possible and not block for any + * significant time, as this callback delays submission of data to the audio + * device, which can cause audio playback problems. + * + * The postmix callback _must_ be able to handle any audio data format + * specified in `spec`, which can change between callbacks if the audio device + * changed. However, this only covers frequency and channel count; data is + * always provided here in SDL_AUDIO_F32 format. + * + * The postmix callback runs _after_ logical device gain and audiostream gain + * have been applied, which is to say you can make the output data louder at + * this point than the gain settings would suggest. + * + * \param userdata a pointer provided by the app through + * SDL_SetAudioPostmixCallback, for its own use. + * \param spec the current format of audio that is to be submitted to the + * audio device. + * \param buffer the buffer of audio samples to be submitted. The callback can + * inspect and/or modify this data. + * \param buflen the size of `buffer` in bytes. + * + * \threadsafety This will run from a background thread owned by SDL. The + * application is responsible for locking resources the callback + * touches that need to be protected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetAudioPostmixCallback + */ +typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen); + +/** + * Set a callback that fires when data is about to be fed to an audio device. + * + * This is useful for accessing the final mix, perhaps for writing a + * visualizer or applying a final effect to the audio data before playback. + * + * The buffer is the final mix of all bound audio streams on an opened device; + * this callback will fire regularly for any device that is both opened and + * unpaused. If there is no new data to mix, either because no streams are + * bound to the device or all the streams are empty, this callback will still + * fire with the entire buffer set to silence. + * + * This callback is allowed to make changes to the data; the contents of the + * buffer after this call is what is ultimately passed along to the hardware. + * + * The callback is always provided the data in float format (values from -1.0f + * to 1.0f), but the number of channels or sample rate may be different than + * the format the app requested when opening the device; SDL might have had to + * manage a conversion behind the scenes, or the playback might have jumped to + * new physical hardware when a system default changed, etc. These details may + * change between calls. Accordingly, the size of the buffer might change + * between calls as well. + * + * This callback can run at any time, and from any thread; if you need to + * serialize access to your app's data, you should provide and use a mutex or + * other synchronization device. + * + * All of this to say: there are specific needs this callback can fulfill, but + * it is not the simplest interface. Apps should generally provide audio in + * their preferred format through an SDL_AudioStream and let SDL handle the + * difference. + * + * This function is extremely time-sensitive; the callback should do the least + * amount of work possible and return as quickly as it can. The longer the + * callback runs, the higher the risk of audio dropouts or other problems. + * + * This function will block until the audio device is in between iterations, + * so any existing callback that might be running will finish before this + * function sets the new callback and returns. + * + * Setting a NULL callback function disables any previously-set callback. + * + * \param devid the ID of an opened audio device. + * \param callback a callback function to be called. Can be NULL. + * \param userdata app-controlled pointer passed to callback. Can be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); + + +/** + * Load the audio data of a WAVE file into memory. + * + * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to + * be valid pointers. The entire data portion of the file is then loaded into + * memory and decoded if necessary. + * + * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and + * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and + * A-law and mu-law (8 bits). Other formats are currently unsupported and + * cause an error. + * + * If this function succeeds, the return value is zero and the pointer to the + * audio data allocated by the function is written to `audio_buf` and its + * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`, + * `channels`, and `format` are set to the values of the audio data in the + * buffer. + * + * It's necessary to use SDL_free() to free the audio data returned in + * `audio_buf` when it is no longer used. + * + * Because of the underspecification of the .WAV format, there are many + * problematic files in the wild that cause issues with strict decoders. To + * provide compatibility with these files, this decoder is lenient in regards + * to the truncation of the file, the fact chunk, and the size of the RIFF + * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, + * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to + * tune the behavior of the loading process. + * + * Any file that is invalid (due to truncation, corruption, or wrong values in + * the headers), too big, or unsupported causes an error. Additionally, any + * critical I/O error from the data source will terminate the loading process + * with an error. The function returns NULL on error and in all cases (with + * the exception of `src` being NULL), an appropriate error message will be + * set. + * + * It is required that the data source supports seeking. + * + * Example: + * + * ```c + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); + * ``` + * + * Note that the SDL_LoadWAV function does this same thing for you, but in a + * less messy way: + * + * ```c + * SDL_LoadWAV("sample.wav", &spec, &buf, &len); + * ``` + * + * \param src the data source for the WAVE data. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE + * data's format details on successful return. + * \param audio_buf a pointer filled with the audio data, allocated by the + * function. + * \param audio_len a pointer filled with the length of the audio data buffer + * in bytes. + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is + * filled with the length of that audio buffer in bytes. + * + * This function returns false if the .WAV file cannot be opened, + * uses an unknown data format, or is corrupt; call SDL_GetError() + * for more information. + * + * When the application is done with the data returned in + * `audio_buf`, it should call SDL_free() to dispose of it. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_LoadWAV + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); + +/** + * Loads a WAV from a file path. + * + * This is a convenience function that is effectively the same as: + * + * ```c + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); + * ``` + * + * \param path the file path of the WAV file to open. + * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE + * data's format details on successful return. + * \param audio_buf a pointer filled with the audio data, allocated by the + * function. + * \param audio_len a pointer filled with the length of the audio data buffer + * in bytes. + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is + * filled with the length of that audio buffer in bytes. + * + * This function returns false if the .WAV file cannot be opened, + * uses an unknown data format, or is corrupt; call SDL_GetError() + * for more information. + * + * When the application is done with the data returned in + * `audio_buf`, it should call SDL_free() to dispose of it. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_LoadWAV_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); + +/** + * Mix audio data in a specified format. + * + * This takes an audio buffer `src` of `len` bytes of `format` data and mixes + * it into `dst`, performing addition, volume adjustment, and overflow + * clipping. The buffer pointed to by `dst` must also be `len` bytes of + * `format` data. + * + * This is provided for convenience -- you can mix your own audio data. + * + * Do not use this function for mixing together more than two streams of + * sample data. The output from repeated application of this function may be + * distorted by clipping, because there is no accumulator with greater range + * than the input (not to mention this being an inefficient way of doing it). + * + * It is a common misconception that this function is required to write audio + * data to an output stream in an audio callback. While you can do that, + * SDL_MixAudio() is really only needed when you're mixing a single audio + * stream with a volume adjustment. + * + * \param dst the destination for the mixed audio. + * \param src the source audio buffer to be mixed. + * \param format the SDL_AudioFormat structure representing the desired audio + * format. + * \param len the length of the audio buffer in bytes. + * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full + * audio volume. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); + +/** + * Convert some audio data of one format to another format. + * + * Please note that this function is for convenience, but should not be used + * to resample audio in blocks, as it will introduce audio artifacts on the + * boundaries. You should only use this function if you are converting audio + * data in its entirety in one call. If you want to convert audio in smaller + * chunks, use an SDL_AudioStream, which is designed for this situation. + * + * Internally, this function creates and destroys an SDL_AudioStream on each + * use, so it's also less efficient than using one directly, if you need to + * convert multiple times. + * + * \param src_spec the format details of the input audio. + * \param src_data the audio data to be converted. + * \param src_len the len of src_data. + * \param dst_spec the format details of the output audio. + * \param dst_data will be filled with a pointer to converted audio data, + * which should be freed with SDL_free(). On error, it will be + * NULL. + * \param dst_len will be filled with the len of dst_data. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); + +/** + * Get the human readable name of an audio format. + * + * \param format the audio format to query. + * \returns the human readable name of the specified audio format or + * "SDL_AUDIO_UNKNOWN" if the format isn't recognized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); + +/** + * Get the appropriate memset value for silencing an audio format. + * + * The value returned by this function can be used as the second argument to + * memset (or SDL_memset) to set an audio buffer in a specific format to + * silence. + * + * \param format the audio data format to query. + * \returns a byte value that can be passed to memset. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_audio_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_begin_code.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_begin_code.h new file mode 100644 index 0000000000..a6b47cf4b9 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_begin_code.h @@ -0,0 +1,486 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: BeginCode */ + +/** + * # 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. + */ + +/* This shouldn't be nested -- included it around code only. */ +#ifdef SDL_begin_code_h +#error Nested inclusion of SDL_begin_code.h +#endif +#define SDL_begin_code_h + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + +#ifndef SDL_DEPRECATED +# if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ +# define SDL_DEPRECATED __attribute__((deprecated)) +# elif defined(_MSC_VER) +# define SDL_DEPRECATED __declspec(deprecated) +# else +# define SDL_DEPRECATED +# endif +#endif + +#ifndef SDL_UNUSED +# ifdef __GNUC__ +# define SDL_UNUSED __attribute__((unused)) +# else +# define SDL_UNUSED +# endif +#endif + +/* Some compilers use a special export keyword */ +#ifndef SDL_DECLSPEC +# if defined(SDL_PLATFORM_WINDOWS) +# ifdef DLL_EXPORT +# define SDL_DECLSPEC __declspec(dllexport) +# else +# define SDL_DECLSPEC +# endif +# else +# if defined(__GNUC__) && __GNUC__ >= 4 +# define SDL_DECLSPEC __attribute__ ((visibility("default"))) +# else +# define SDL_DECLSPEC +# endif +# endif +#endif + +/* By default SDL uses the C calling convention */ +#ifndef SDLCALL +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) +#define SDLCALL __cdecl +#else +#define SDLCALL +#endif +#endif /* SDLCALL */ + +/* Force structure packing at 4 byte alignment. + This is necessary if the header is included in code which has structure + packing set to an alternate value, say for loading structures from disk. + The packing is reset to the previous value in SDL_close_code.h + */ +#if defined(_MSC_VER) || defined(__MWERKS__) || defined(__BORLANDC__) +#ifdef _MSC_VER +#pragma warning(disable: 4103) +#endif +#ifdef __clang__ +#pragma clang diagnostic ignored "-Wpragma-pack" +#endif +#ifdef __BORLANDC__ +#pragma nopackwarning +#endif +#ifdef _WIN64 +/* Use 8-byte alignment on 64-bit architectures, so pointers are aligned */ +#pragma pack(push,8) +#else +#pragma pack(push,4) +#endif +#endif /* Compiler needs structure packing set */ + +#ifndef SDL_INLINE +#ifdef __GNUC__ +#define SDL_INLINE __inline__ +#elif defined(_MSC_VER) || defined(__BORLANDC__) || \ + defined(__DMC__) || defined(__SC__) || \ + defined(__WATCOMC__) || defined(__LCC__) || \ + defined(__DECC) || defined(__CC_ARM) +#define SDL_INLINE __inline +#ifndef __inline__ +#define __inline__ __inline +#endif +#else +#define SDL_INLINE inline +#ifndef __inline__ +#define __inline__ inline +#endif +#endif +#endif /* SDL_INLINE not defined */ + +#ifndef SDL_FORCE_INLINE +#ifdef _MSC_VER +#define SDL_FORCE_INLINE __forceinline +#elif ( (defined(__GNUC__) && (__GNUC__ >= 4)) || defined(__clang__) ) +#define SDL_FORCE_INLINE __attribute__((always_inline)) static __inline__ +#else +#define SDL_FORCE_INLINE static SDL_INLINE +#endif +#endif /* SDL_FORCE_INLINE not defined */ + +#ifndef SDL_NORETURN +#ifdef __GNUC__ +#define SDL_NORETURN __attribute__((noreturn)) +#elif defined(_MSC_VER) +#define SDL_NORETURN __declspec(noreturn) +#else +#define SDL_NORETURN +#endif +#endif /* SDL_NORETURN not defined */ + +#ifdef __clang__ +#if __has_feature(attribute_analyzer_noreturn) +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) +#endif +#endif + +#ifndef SDL_ANALYZER_NORETURN +#define SDL_ANALYZER_NORETURN +#endif + +/* Apparently this is needed by several Windows compilers */ +#ifndef __MACH__ +#ifndef NULL +#ifdef __cplusplus +#define NULL 0 +#else +#define NULL ((void *)0) +#endif +#endif /* NULL */ +#endif /* ! macOS - breaks precompiled headers */ + +#ifndef SDL_FALLTHROUGH +#if (defined(__cplusplus) && __cplusplus >= 201703L) || \ + (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L) +#define SDL_FALLTHROUGH [[fallthrough]] +#else +#if defined(__has_attribute) && !defined(__SUNPRO_C) && !defined(__SUNPRO_CC) +#define SDL_HAS_FALLTHROUGH __has_attribute(__fallthrough__) +#else +#define SDL_HAS_FALLTHROUGH 0 +#endif /* __has_attribute */ +#if SDL_HAS_FALLTHROUGH && \ + ((defined(__GNUC__) && __GNUC__ >= 7) || \ + (defined(__clang_major__) && __clang_major__ >= 10)) +#define SDL_FALLTHROUGH __attribute__((__fallthrough__)) +#else +#define SDL_FALLTHROUGH do {} while (0) /* fallthrough */ +#endif /* SDL_HAS_FALLTHROUGH */ +#undef SDL_HAS_FALLTHROUGH +#endif /* C++17 or C2x */ +#endif /* SDL_FALLTHROUGH not defined */ + +#ifndef SDL_NODISCARD +#if (defined(__cplusplus) && __cplusplus >= 201703L) || \ + (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L) +#define SDL_NODISCARD [[nodiscard]] +#elif ( (defined(__GNUC__) && (__GNUC__ >= 4)) || defined(__clang__) ) +#define SDL_NODISCARD __attribute__((warn_unused_result)) +#elif defined(_MSC_VER) && (_MSC_VER >= 1700) +#define SDL_NODISCARD _Check_return_ +#else +#define SDL_NODISCARD +#endif /* C++17 or C23 */ +#endif /* SDL_NODISCARD not defined */ + +#ifndef SDL_MALLOC +#if defined(__GNUC__) && (__GNUC__ >= 3) +#define SDL_MALLOC __attribute__((malloc)) +/** FIXME +#elif defined(_MSC_VER) +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) +**/ +#else +#define SDL_MALLOC +#endif +#endif /* SDL_MALLOC not defined */ + +#ifndef SDL_ALLOC_SIZE +#if (defined(__clang__) && __clang_major__ >= 4) || (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))) +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) +#elif defined(_MSC_VER) +#define SDL_ALLOC_SIZE(p) +#else +#define SDL_ALLOC_SIZE(p) +#endif +#endif /* SDL_ALLOC_SIZE not defined */ + +#ifndef SDL_ALLOC_SIZE2 +#if (defined(__clang__) && __clang_major__ >= 4) || (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))) +#define SDL_ALLOC_SIZE2(p1, p2) __attribute__((alloc_size(p1, p2))) +#elif defined(_MSC_VER) +#define SDL_ALLOC_SIZE2(p1, p2) +#else +#define SDL_ALLOC_SIZE2(p1, p2) +#endif +#endif /* SDL_ALLOC_SIZE2 not defined */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_bits.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_bits.h similarity index 59% rename from code/thirdparty/SDL2-2.32.8/include/SDL_bits.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_bits.h index 747f556511..7435ce6d93 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_bits.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_bits.h @@ -28,25 +28,14 @@ #ifndef SDL_bits_h_ #define SDL_bits_h_ -#include "SDL_stdinc.h" +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif -/** - * \file SDL_bits.h - */ - -/** - * Get the index of the most significant bit. Result is undefined when called - * with 0. This operation can also be stated as "count leading zeroes" and - * "log base 2". - * - * \return the index of the most significant bit, or -1 if the value is 0. - */ #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -57,13 +46,24 @@ extern __inline int _SDL_bsr_watcom(Uint32); #endif /** - * Use this function to get the index of the most significant (set) bit in a + * Get the index of the most significant (set) bit in a 32-bit number. + * + * Result is undefined when called with 0. This operation can also be stated + * as "count leading zeroes" and "log base 2". + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the 32-bit value to examine. + * \returns the index of the most significant bit, or -1 if the value is 0. * - * \param x the number to find the MSB of. - * \returns the index of the most significant bit of x, or -1 if x is 0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int -SDL_MostSignificantBitIndex32(Uint32 x) +SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { #if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)) /* Count Leading Zeroes builtin in GCC. @@ -78,10 +78,10 @@ SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -112,21 +112,36 @@ SDL_MostSignificantBitIndex32(Uint32 x) #endif } -SDL_FORCE_INLINE SDL_bool -SDL_HasExactlyOneBitSet32(Uint32 x) +/** + * Determine if a unsigned 32-bit value has exactly one bit set. + * + * If there are no bits set (`x` is zero), or more than one bit set, this + * returns false. If any one bit is exclusively set, this returns true. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the 32-bit value to examine. + * \returns true if exactly one bit is set in `x`, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_bits_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_blendmode.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_blendmode.h similarity index 72% rename from code/thirdparty/SDL2-2.32.8/include/SDL_blendmode.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_blendmode.h index c0c6811331..8f00cbcafb 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_blendmode.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_blendmode.h @@ -22,58 +22,68 @@ /** * # CategoryBlendmode * - * Header file declaring the SDL_BlendMode enumeration + * Blend modes decide how two colors will mix together. There are both + * standard modes for basic needs and a means to create custom modes, + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ #define SDL_blendmode_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif /** - * The blend mode used in SDL_RenderCopy() and drawing operations. + * A set of blend modes used in drawing operations. + * + * These predefined blend modes are supported everywhere. + * + * Additional values may be obtained from SDL_ComposeCustomBlendMode. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_ComposeCustomBlendMode */ -typedef enum SDL_BlendMode -{ - SDL_BLENDMODE_NONE = 0x00000000, /**< no blending - dstRGBA = srcRGBA */ - SDL_BLENDMODE_BLEND = 0x00000001, /**< alpha blending - dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA)) - dstA = srcA + (dstA * (1-srcA)) */ - SDL_BLENDMODE_ADD = 0x00000002, /**< additive blending - dstRGB = (srcRGB * srcA) + dstRGB - dstA = dstA */ - SDL_BLENDMODE_MOD = 0x00000004, /**< color modulate - dstRGB = srcRGB * dstRGB - dstA = dstA */ - SDL_BLENDMODE_MUL = 0x00000008, /**< color multiply - dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA)) - dstA = dstA */ - SDL_BLENDMODE_INVALID = 0x7FFFFFFF +typedef Uint32 SDL_BlendMode; - /* Additional custom blend modes can be returned by SDL_ComposeCustomBlendMode() */ - -} SDL_BlendMode; +#define SDL_BLENDMODE_NONE 0x00000000u /**< no blending: dstRGBA = srcRGBA */ +#define SDL_BLENDMODE_BLEND 0x00000001u /**< alpha blending: dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA)), dstA = srcA + (dstA * (1-srcA)) */ +#define SDL_BLENDMODE_BLEND_PREMULTIPLIED 0x00000010u /**< pre-multiplied alpha blending: dstRGBA = srcRGBA + (dstRGBA * (1-srcA)) */ +#define SDL_BLENDMODE_ADD 0x00000002u /**< additive blending: dstRGB = (srcRGB * srcA) + dstRGB, dstA = dstA */ +#define SDL_BLENDMODE_ADD_PREMULTIPLIED 0x00000020u /**< pre-multiplied additive blending: dstRGB = srcRGB + dstRGB, dstA = dstA */ +#define SDL_BLENDMODE_MOD 0x00000004u /**< color modulate: dstRGB = srcRGB * dstRGB, dstA = dstA */ +#define SDL_BLENDMODE_MUL 0x00000008u /**< color multiply: dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA)), dstA = dstA */ +#define SDL_BLENDMODE_INVALID 0x7FFFFFFFu /** * The blend operation used when combining source and destination pixel - * components + * components. + * + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */ - SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */ - SDL_BLENDOPERATION_REV_SUBTRACT = 0x3, /**< dst - src : supported by D3D9, D3D11, OpenGL, OpenGLES */ - SDL_BLENDOPERATION_MINIMUM = 0x4, /**< min(dst, src) : supported by D3D9, D3D11 */ - SDL_BLENDOPERATION_MAXIMUM = 0x5 /**< max(dst, src) : supported by D3D9, D3D11 */ + SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + SDL_BLENDOPERATION_REV_SUBTRACT = 0x3, /**< dst - src : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + SDL_BLENDOPERATION_MINIMUM = 0x4, /**< min(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + SDL_BLENDOPERATION_MAXIMUM = 0x5 /**< max(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */ } SDL_BlendOperation; /** - * The normalized factor used to multiply pixel components + * The normalized factor used to multiply pixel components. + * + * The blend factors are multiplied with the pixels from a drawing operation + * (src) and the pixels from the render target (dst) before the blend + * operation. The comma-separated factors listed above are always applied in + * the component order red, green, blue, and alpha. + * + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -130,23 +140,16 @@ typedef enum SDL_BlendFactor * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will * return with an error if the blend mode is not supported. * - * This list describes the support of custom blend modes for each renderer in - * SDL 2.0.6. All renderers support the four blend modes listed in the - * SDL_BlendMode enumeration. + * This list describes the support of custom blend modes for each renderer. + * All renderers support the four blend modes listed in the SDL_BlendMode + * enumeration. * * - **direct3d**: Supports all operations with all factors. However, some * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and * `SDL_BLENDOPERATION_MAXIMUM`. * - **direct3d11**: Same as Direct3D 9. * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all - * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL - * 2.0.6. - * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all - * factors. Color and alpha factors need to be the same. OpenGL ES 1 - * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT` - * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha - * operations being different from each other. May support color and alpha - * factors being different from each other. + * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly here. * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`, * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` * operations with all factors. @@ -174,14 +177,16 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 2.0.6. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode * \sa SDL_SetTextureBlendMode * \sa SDL_GetTextureBlendMode */ -extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor, +extern SDL_DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor, SDL_BlendFactor dstColorFactor, SDL_BlendOperation colorOperation, SDL_BlendFactor srcAlphaFactor, @@ -192,8 +197,6 @@ extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_blendmode_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_camera.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_camera.h new file mode 100644 index 0000000000..5f3911fdf9 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_camera.h @@ -0,0 +1,519 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryCamera + * + * Video capture for the SDL library. + * + * This API lets apps read input from video sources, like webcams. Camera + * devices can be enumerated, queried, and opened. Once opened, it will + * provide SDL_Surface objects as new frames of video come in. These surfaces + * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. + */ + +#ifndef SDL_camera_h_ +#define SDL_camera_h_ + +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * This is a unique ID for a camera device for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the device is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetCameras + */ +typedef Uint32 SDL_CameraID; + +/** + * The opaque structure used to identify an opened SDL camera. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Camera SDL_Camera; + +/** + * The details of an output format for a camera device. + * + * Cameras often support multiple formats; each one will be encapsulated in + * this struct. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetCameraSupportedFormats + * \sa SDL_GetCameraFormat + */ +typedef struct SDL_CameraSpec +{ + SDL_PixelFormat format; /**< Frame format */ + SDL_Colorspace colorspace; /**< Frame colorspace */ + int width; /**< Frame width */ + int height; /**< Frame height */ + int framerate_numerator; /**< Frame rate numerator ((num / denom) == FPS, (denom / num) == duration in seconds) */ + int framerate_denominator; /**< Frame rate demoninator ((num / denom) == FPS, (denom / num) == duration in seconds) */ +} SDL_CameraSpec; + +/** + * The position of camera in relation to system device. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetCameraPosition + */ +typedef enum SDL_CameraPosition +{ + SDL_CAMERA_POSITION_UNKNOWN, + SDL_CAMERA_POSITION_FRONT_FACING, + SDL_CAMERA_POSITION_BACK_FACING +} SDL_CameraPosition; + + +/** + * Use this function to get the number of built-in camera drivers. + * + * This function returns a hardcoded number. This never returns a negative + * value; if there are no drivers compiled into this build of SDL, this + * function returns zero. The presence of a driver in this list does not mean + * it will function, it just means SDL is capable of interacting with that + * interface. For example, a build of SDL might have v4l2 support, but if + * there's no kernel support available, SDL's v4l2 driver would fail if used. + * + * By default, SDL tries all drivers, in its preferred order, until one is + * found to be usable. + * + * \returns the number of built-in camera drivers. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCameraDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); + +/** + * Use this function to get the name of a built in camera driver. + * + * The list of camera drivers is given in the order that they are normally + * initialized by default; the drivers that seem more reasonable to choose + * first (as far as the SDL developers believe) are earlier in the list. + * + * The names of drivers are all simple, low-ASCII identifiers, like "v4l2", + * "coremedia" or "android". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of the camera driver; the value ranges from 0 to + * SDL_GetNumCameraDrivers() - 1. + * \returns the name of the camera driver at the requested index, or NULL if + * an invalid index was specified. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumCameraDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); + +/** + * Get the name of the current camera driver. + * + * The names of drivers are all simple, low-ASCII identifiers, like "v4l2", + * "coremedia" or "android". These never have Unicode characters, and are not + * meant to be proper names. + * + * \returns the name of the current camera driver or NULL if no driver has + * been initialized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); + +/** + * Get a list of currently connected camera devices. + * + * \param count a pointer filled in with the number of cameras returned, may + * be NULL. + * \returns a 0 terminated array of camera instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenCamera + */ +extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); + +/** + * Get the list of native formats/sizes a camera supports. + * + * This returns a list of all formats and frame sizes that a specific camera + * can offer. This is useful if your app can accept a variety of image formats + * and sizes and so want to find the optimal spec that doesn't require + * conversion. + * + * This function isn't strictly required; if you call SDL_OpenCamera with a + * NULL spec, SDL will choose a native format for you, and if you instead + * specify a desired format, it will transparently convert to the requested + * format on your behalf. + * + * If `count` is not NULL, it will be filled with the number of elements in + * the returned array. + * + * Note that it's legal for a camera to supply an empty list. This is what + * will happen on Emscripten builds, since that platform won't tell _anything_ + * about available cameras until you've opened one, and won't even tell if + * there _is_ a camera until the user has given you permission to check + * through a scary warning popup. + * + * \param instance_id the camera device instance ID. + * \param count a pointer filled in with the number of elements in the list, + * may be NULL. + * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCameras + * \sa SDL_OpenCamera + */ +extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID instance_id, int *count); + +/** + * Get the human-readable device name for a camera. + * + * \param instance_id the camera device instance ID. + * \returns a human-readable device name or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCameras + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id); + +/** + * Get the position of the camera in relation to the system. + * + * Most platforms will report UNKNOWN, but mobile devices, like phones, can + * often make a distinction between cameras on the front of the device (that + * points towards the user, for taking "selfies") and cameras on the back (for + * filming in the direction the user is facing). + * + * \param instance_id the camera device instance ID. + * \returns the position of the camera on the system hardware. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCameras + */ +extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraID instance_id); + +/** + * Open a video recording device (a "camera"). + * + * You can open the device with any reasonable spec, and if the hardware can't + * directly support it, it will convert data seamlessly to the requested + * format. This might incur overhead, including scaling of image data. + * + * If you would rather accept whatever format the device offers, you can pass + * a NULL spec here and it will choose one for you (and you can use + * SDL_Surface's conversion/scaling functions directly if necessary). + * + * You can call SDL_GetCameraFormat() to get the actual data format if passing + * a NULL spec here. You can see the exact specs a device can support without + * conversion with SDL_GetCameraSupportedFormats(). + * + * SDL will not attempt to emulate framerate; it will try to set the hardware + * to the rate closest to the requested speed, but it won't attempt to limit + * or duplicate frames artificially; call SDL_GetCameraFormat() to see the + * actual framerate of the opened the device, and check your timestamps if + * this is crucial to your app! + * + * Note that the camera is not usable until the user approves its use! On some + * platforms, the operating system will prompt the user to permit access to + * the camera, and they can choose Yes or No at that point. Until they do, the + * camera will not be usable. The app should either wait for an + * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! + * + * \param instance_id the camera device instance ID. + * \param spec the desired format for data the device will provide. Can be + * NULL. + * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCameras + * \sa SDL_GetCameraFormat + */ +extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id, const SDL_CameraSpec *spec); + +/** + * Query if camera access has been approved by the user. + * + * Cameras will not function between when the device is opened by the app and + * when the user permits access to the hardware. On some platforms, this + * presents as a popup dialog where the user has to explicitly approve access; + * on others the approval might be implicit and not alert the user at all. + * + * This function can be used to check the status of that approval. It will + * return 0 if still waiting for user response, 1 if the camera is approved + * for use, and -1 if the user denied access. + * + * Instead of polling with this function, you can wait for a + * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event + * in the standard SDL event loop, which is guaranteed to be sent once when + * permission to use the camera is decided. + * + * If a camera is declined, there's nothing to be done but call + * SDL_CloseCamera() to dispose of it. + * + * \param camera the opened camera device to query. + * \returns -1 if user denied access to the camera, 1 if user approved access, + * 0 if no decision has been made yet. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenCamera + * \sa SDL_CloseCamera + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera); + +/** + * Get the instance ID of an opened camera. + * + * \param camera an SDL_Camera to query. + * \returns the instance ID of the specified camera on success or 0 on + * failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenCamera + */ +extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); + +/** + * Get the properties associated with an opened camera. + * + * \param camera the SDL_Camera obtained from SDL_OpenCamera(). + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); + +/** + * Get the spec that a camera is using when generating images. + * + * Note that this might not be the native format of the hardware, as SDL might + * be converting to this format behind the scenes. + * + * If the system is waiting for the user to approve access to the camera, as + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an + * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. + * + * \param camera opened camera device. + * \param spec the SDL_CameraSpec to be initialized by this function. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenCamera + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); + +/** + * Acquire a frame. + * + * The frame is a memory pointer to the image data, whose size and format are + * given by the spec requested when opening the device. + * + * This is a non blocking API. If there is a frame available, a non-NULL + * surface is returned, and timestampNS will be filled with a non-zero value. + * + * Note that an error case can also return NULL, but a NULL by itself is + * normal and just signifies that a new frame is not yet available. Note that + * even if a camera device fails outright (a USB camera is unplugged while in + * use, etc), SDL will send an event separately to notify the app, but + * continue to provide blank frames at ongoing intervals until + * SDL_CloseCamera() is called, so real failure here is almost always an out + * of memory condition. + * + * After use, the frame should be released with SDL_ReleaseCameraFrame(). If + * you don't do this, the system may stop providing more video! + * + * Do not call SDL_DestroySurface() on the returned surface! It must be given + * back to the camera subsystem with SDL_ReleaseCameraFrame! + * + * If the system is waiting for the user to approve access to the camera, as + * some platforms require, this will return NULL (no frames available); you + * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. + * + * \param camera opened camera device. + * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on + * error. Can be NULL. + * \returns a new frame of video on success, NULL if none is currently + * available. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReleaseCameraFrame + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS); + +/** + * Release a frame of video acquired from a camera. + * + * Let the back-end re-use the internal buffer for camera. + * + * This function _must_ be called only on surface objects returned by + * SDL_AcquireCameraFrame(). This function should be called as quickly as + * possible after acquisition, as SDL keeps a small FIFO queue of surfaces for + * video frames; if surfaces aren't released in a timely manner, SDL may drop + * upcoming video frames from the camera. + * + * If the app needs to keep the surface for a significant time, they should + * make a copy of it and release the original. + * + * The app should not use the surface again after calling this function; + * assume the surface is freed and the pointer is invalid. + * + * \param camera opened camera device. + * \param frame the video frame surface to release. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireCameraFrame + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame); + +/** + * Use this function to shut down camera processing and close the camera + * device. + * + * \param camera opened camera device. + * + * \threadsafety It is safe to call this function from any thread, but no + * thread may reference `device` once this function is called. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenCamera + */ +extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_camera_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_clipboard.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_clipboard.h new file mode 100644 index 0000000000..0d3cbb499b --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_clipboard.h @@ -0,0 +1,331 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryClipboard + * + * SDL provides access to the system clipboard, both for reading information + * from other processes and publishing information of its own. + * + * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. + */ + +#ifndef SDL_clipboard_h_ +#define SDL_clipboard_h_ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* Function prototypes */ + +/** + * Put UTF-8 text into the clipboard. + * + * \param text the text to store in the clipboard. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetClipboardText + * \sa SDL_HasClipboardText + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); + +/** + * Get UTF-8 text from the clipboard. + * + * This functions returns an empty string if there was not enough memory left + * for a copy of the clipboard's content. + * + * \returns the clipboard text on success or an empty string on failure; call + * SDL_GetError() for more information. This should be freed with + * SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasClipboardText + * \sa SDL_SetClipboardText + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); + +/** + * Query whether the clipboard exists and contains a non-empty text string. + * + * \returns true if the clipboard has text, or false if it does not. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetClipboardText + * \sa SDL_SetClipboardText + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); + +/** + * Put UTF-8 text into the primary selection. + * + * \param text the text to store in the primary selection. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPrimarySelectionText + * \sa SDL_HasPrimarySelectionText + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); + +/** + * Get UTF-8 text from the primary selection. + * + * This functions returns an empty string if there was not enough memory left + * for a copy of the primary selection's content. + * + * \returns the primary selection text on success or an empty string on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasPrimarySelectionText + * \sa SDL_SetPrimarySelectionText + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); + +/** + * Query whether the primary selection exists and contains a non-empty text + * string. + * + * \returns true if the primary selection has text, or false if it does not. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPrimarySelectionText + * \sa SDL_SetPrimarySelectionText + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); + +/** + * Callback function that will be called when data for the specified mime-type + * is requested by the OS. + * + * The callback function is called with NULL as the mime_type when the + * clipboard is cleared or new data is set. The clipboard is automatically + * cleared in SDL_Quit(). + * + * \param userdata a pointer to provided user data. + * \param mime_type the requested mime-type. + * \param size a pointer filled in with the length of the returned data. + * \returns a pointer to the data for the provided mime-type. Returning NULL + * or setting length to 0 will cause no data to be sent to the + * "receiver". It is up to the receiver to handle this. Essentially + * returning no data is more or less undefined behavior and may cause + * breakage in receiving applications. The returned data will not be + * freed so it needs to be retained and dealt with internally. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size); + +/** + * Callback function that will be called when the clipboard is cleared, or new + * data is set. + * + * \param userdata a pointer to provided user data. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); + +/** + * Offer clipboard data to the OS. + * + * Tell the operating system that the application is offering clipboard data + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and + * respond with the data for the requested mime-type. + * + * The size of text data does not include any terminator, and the text does + * not need to be null terminated (e.g. you can directly copy a portion of a + * document). + * + * \param callback a function pointer to the function that provides the + * clipboard data. + * \param cleanup a function pointer to the function that cleans up the + * clipboard data. + * \param userdata an opaque pointer that will be forwarded to the callbacks. + * \param mime_types a list of mime-types that are being offered. + * \param num_mime_types the number of mime-types in the mime_types list. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearClipboardData + * \sa SDL_GetClipboardData + * \sa SDL_HasClipboardData + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); + +/** + * Clear the clipboard data. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); + +/** + * Get the data from clipboard for a given mime type. + * + * The size of text data does not include the terminator, but the text is + * guaranteed to be null terminated. + * + * \param mime_type the mime type to read from the clipboard. + * \param size a pointer filled in with the length of the returned data. + * \returns the retrieved data buffer or NULL on failure; call SDL_GetError() + * for more information. This should be freed with SDL_free() when it + * is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasClipboardData + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size); + +/** + * Query whether there is data in the clipboard for the provided mime type. + * + * \param mime_type the mime type to check for data for. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + * \sa SDL_GetClipboardData + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \param num_mime_types a pointer filled with the number of mime types, may + * be NULL. + * \returns a null terminated array of strings with mime types, or NULL on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_clipboard_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/close_code.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_close_code.h similarity index 79% rename from code/thirdparty/SDL2-2.32.8/include/close_code.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_close_code.h index f991f458d5..da1dea7fac 100644 --- a/code/thirdparty/SDL2-2.32.8/include/close_code.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_close_code.h @@ -19,15 +19,16 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file close_code.h +/* + * This file reverses the effects of SDL_begin_code.h and should be included + * after you finish any function and structure declarations in your headers. * - * This file reverses the effects of begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h -#error close_code.h included without matching begin_code.h +#error SDL_close_code.h included without matching SDL_begin_code.h #endif #undef SDL_begin_code_h diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_copying.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_copying.h similarity index 95% rename from code/thirdparty/SDL2-2.32.8/include/SDL_copying.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_copying.h index bde7431896..747bd35700 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_copying.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_copying.h @@ -18,3 +18,5 @@ misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. */ + +/* Header file containing SDL's license. */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_cpuinfo.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_cpuinfo.h new file mode 100644 index 0000000000..1745bd9349 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_cpuinfo.h @@ -0,0 +1,353 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: CPUInfo */ + +/** + * # CategoryCPUInfo + * + * CPU feature detection for SDL. + * + * These functions are largely concerned with reporting if the system has + * access to various SIMD instruction sets, but also has other important info + * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). + */ + +#ifndef SDL_cpuinfo_h_ +#define SDL_cpuinfo_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * A guess for the cacheline size used for padding. + * + * Most x86 processors have a 64 byte cache line. The 64-bit PowerPC + * processors have a 128 byte cache line. We use the larger value to be + * generally safe. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_CACHELINE_SIZE 128 + +/** + * Get the number of logical CPU cores available. + * + * \returns the total number of logical CPU cores. On CPUs that include + * technologies such as hyperthreading, the number of logical cores + * may be more than the number of physical cores. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); + +/** + * Determine the L1 cache line size of the CPU. + * + * This is useful for determining multi-threaded structure padding or SIMD + * prefetch sizes. + * + * \returns the L1 cache line size of the CPU, in bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); + +/** + * Determine whether the CPU has AltiVec features. + * + * This always returns false on CPUs that aren't using PowerPC instruction + * sets. + * + * \returns true if the CPU has AltiVec features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); + +/** + * Determine whether the CPU has MMX features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has MMX features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); + +/** + * Determine whether the CPU has SSE features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has SSE features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasSSE2 + * \sa SDL_HasSSE3 + * \sa SDL_HasSSE41 + * \sa SDL_HasSSE42 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); + +/** + * Determine whether the CPU has SSE2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has SSE2 features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasSSE + * \sa SDL_HasSSE3 + * \sa SDL_HasSSE41 + * \sa SDL_HasSSE42 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); + +/** + * Determine whether the CPU has SSE3 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has SSE3 features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasSSE + * \sa SDL_HasSSE2 + * \sa SDL_HasSSE41 + * \sa SDL_HasSSE42 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); + +/** + * Determine whether the CPU has SSE4.1 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has SSE4.1 features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasSSE + * \sa SDL_HasSSE2 + * \sa SDL_HasSSE3 + * \sa SDL_HasSSE42 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); + +/** + * Determine whether the CPU has SSE4.2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has SSE4.2 features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasSSE + * \sa SDL_HasSSE2 + * \sa SDL_HasSSE3 + * \sa SDL_HasSSE41 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); + +/** + * Determine whether the CPU has AVX features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has AVX features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasAVX2 + * \sa SDL_HasAVX512F + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); + +/** + * Determine whether the CPU has AVX2 features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has AVX2 features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasAVX + * \sa SDL_HasAVX512F + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); + +/** + * Determine whether the CPU has AVX-512F (foundation) features. + * + * This always returns false on CPUs that aren't using Intel instruction sets. + * + * \returns true if the CPU has AVX-512F features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasAVX + * \sa SDL_HasAVX2 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); + +/** + * Determine whether the CPU has ARM SIMD (ARMv6) features. + * + * This is different from ARM NEON, which is a different instruction set. + * + * This always returns false on CPUs that aren't using ARM instruction sets. + * + * \returns true if the CPU has ARM SIMD features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasNEON + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); + +/** + * Determine whether the CPU has NEON (ARM SIMD) features. + * + * This always returns false on CPUs that aren't using ARM instruction sets. + * + * \returns true if the CPU has ARM NEON features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); + +/** + * Determine whether the CPU has LSX (LOONGARCH SIMD) features. + * + * This always returns false on CPUs that aren't using LOONGARCH instruction + * sets. + * + * \returns true if the CPU has LOONGARCH LSX features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); + +/** + * Determine whether the CPU has LASX (LOONGARCH SIMD) features. + * + * This always returns false on CPUs that aren't using LOONGARCH instruction + * sets. + * + * \returns true if the CPU has LOONGARCH LASX features or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); + +/** + * Get the amount of RAM configured in the system. + * + * \returns the amount of RAM configured in the system in MiB. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); + +/** + * Report the alignment this system needs for SIMD allocations. + * + * This will return the minimum number of bytes to which a pointer must be + * aligned to be compatible with SIMD instructions on the current machine. For + * example, if the machine supports SSE only, it will return 16, but if it + * supports AVX-512F, it'll return 64 (etc). This only reports values for + * instruction sets SDL knows about, so if your SDL build doesn't have + * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and + * not 64 for the AVX-512 instructions that exist but SDL doesn't know about. + * Plan accordingly. + * + * \returns the alignment in bytes needed for available, known SIMD + * instructions. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_aligned_alloc + * \sa SDL_aligned_free + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_GetSIMDAlignment(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_cpuinfo_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_dialog.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_dialog.h new file mode 100644 index 0000000000..ddb9e24d5f --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_dialog.h @@ -0,0 +1,341 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryDialog + * + * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. + */ + +#ifndef SDL_dialog_h_ +#define SDL_dialog_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An entry for filters for file dialogs. + * + * `name` is a user-readable label for the filter (for example, "Office + * document"). + * + * `pattern` is a semicolon-separated list of file extensions (for example, + * "doc;docx"). File extensions may only contain alphanumeric characters, + * hyphens, underscores and periods. Alternatively, the whole string can be a + * single asterisk ("*"), which serves as an "All files" filter. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DialogFileCallback + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties + */ +typedef struct SDL_DialogFileFilter +{ + const char *name; + const char *pattern; +} SDL_DialogFileFilter; + +/** + * Callback used by file dialog functions. + * + * The specific usage is described in each function. + * + * If `filelist` is: + * + * - NULL, an error occurred. Details can be obtained with SDL_GetError(). + * - A pointer to NULL, the user either didn't choose any file or canceled the + * dialog. + * - A pointer to non-`NULL`, the user chose one or more files. The argument + * is a null-terminated array of pointers to UTF-8 encoded strings, each + * containing a path. + * + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. + * + * The filter argument is the index of the filter that was selected, or -1 if + * no filter was selected or if the platform or method doesn't support + * fetching the selected filter. + * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * + * \param userdata an app-provided pointer, for the callback's use. + * \param filelist the file(s) chosen by the user. + * \param filter index of the selected filter. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties + */ +typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); + +/** + * Displays a dialog that lets the user select a file on their filesystem. + * + * This is an asynchronous function; it will return immediately, and the + * result will be passed to the callback. + * + * The callback will be invoked with a null-terminated list of files the user + * chose. The list will be empty if the user canceled the dialog, and it will + * be NULL if an error occurred. + * + * Note that the callback may be called from a different thread than the one + * the function was invoked on. + * + * Depending on the platform, the user may be allowed to input paths that + * don't yet exist. + * + * On Linux, dialogs may require XDG Portals, which requires DBus, which + * requires an event-handling loop. Apps that do not use SDL to handle events + * should add a call to SDL_PumpEvents in their main loop. + * + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param window the window that the dialog should be modal for, may be NULL. + * Not all platforms support this option. + * \param filters a list of filters, may be NULL. Not all platforms support + * this option, and platforms that do support it may allow the + * user to ignore the filters. If non-NULL, it must remain + * valid at least until the callback is invoked. + * \param nfilters the number of filters. Ignored if filters is NULL. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. + * \param allow_many if non-zero, the user will be allowed to select multiple + * entries. Not all platforms support this option. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); + +/** + * Displays a dialog that lets the user choose a new or existing file on their + * filesystem. + * + * This is an asynchronous function; it will return immediately, and the + * result will be passed to the callback. + * + * The callback will be invoked with a null-terminated list of files the user + * chose. The list will be empty if the user canceled the dialog, and it will + * be NULL if an error occurred. + * + * Note that the callback may be called from a different thread than the one + * the function was invoked on. + * + * The chosen file may or may not already exist. + * + * On Linux, dialogs may require XDG Portals, which requires DBus, which + * requires an event-handling loop. Apps that do not use SDL to handle events + * should add a call to SDL_PumpEvents in their main loop. + * + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param window the window that the dialog should be modal for, may be NULL. + * Not all platforms support this option. + * \param filters a list of filters, may be NULL. Not all platforms support + * this option, and platforms that do support it may allow the + * user to ignore the filters. If non-NULL, it must remain + * valid at least until the callback is invoked. + * \param nfilters the number of filters. Ignored if filters is NULL. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); + +/** + * Displays a dialog that lets the user select a folder on their filesystem. + * + * This is an asynchronous function; it will return immediately, and the + * result will be passed to the callback. + * + * The callback will be invoked with a null-terminated list of files the user + * chose. The list will be empty if the user canceled the dialog, and it will + * be NULL if an error occurred. + * + * Note that the callback may be called from a different thread than the one + * the function was invoked on. + * + * Depending on the platform, the user may be allowed to input paths that + * don't yet exist. + * + * On Linux, dialogs may require XDG Portals, which requires DBus, which + * requires an event-handling loop. Apps that do not use SDL to handle events + * should add a call to SDL_PumpEvents in their main loop. + * + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param window the window that the dialog should be modal for, may be NULL. + * Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. + * \param allow_many if non-zero, the user will be allowed to select multiple + * entries. Not all platforms support this option. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DialogFileCallback + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_dialog_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_egl.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_egl.h similarity index 99% rename from code/thirdparty/SDL2-2.32.8/include/SDL_egl.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_egl.h index 31290ec25a..65d4e967af 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_egl.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_egl.h @@ -23,9 +23,13 @@ * This is a simple file to encapsulate the EGL API headers. */ -#if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) +#include -#if defined(__vita__) || defined(__psp2__) +#if !defined(_MSC_VER) && !defined(SDL_PLATFORM_ANDROID) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) + +#if defined(SDL_PLATFORM_VITA) +#include +#include #include #endif @@ -415,7 +419,7 @@ typedef HDC EGLNativeDisplayType; typedef HBITMAP EGLNativePixmapType; typedef HWND EGLNativeWindowType; -#elif defined(__EMSCRIPTEN__) +#elif defined(SDL_PLATFORM_EMSCRIPTEN) typedef int EGLNativeDisplayType; typedef int EGLNativePixmapType; diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_endian.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_endian.h new file mode 100644 index 0000000000..2a9b8a34d8 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_endian.h @@ -0,0 +1,645 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryEndian + * + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. + */ + +#ifndef SDL_endian_h_ +#define SDL_endian_h_ + +#include + +#if defined(_MSC_VER) && (_MSC_VER >= 1400) +/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version, + so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */ +#ifdef __clang__ +#ifndef __PRFCHWINTRIN_H +#define __PRFCHWINTRIN_H +static __inline__ void __attribute__((__always_inline__, __nodebug__)) +_m_prefetch(void *__P) +{ + __builtin_prefetch(__P, 0, 3 /* _MM_HINT_T0 */); +} +#endif /* __PRFCHWINTRIN_H */ +#endif /* __clang__ */ + +#include +#endif + +/** + * \name The two types of endianness + */ +/* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ +#define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ +#define SDL_BIG_ENDIAN 4321 + +/* @} */ + +#ifndef SDL_BYTEORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) +#include +#define SDL_BYTEORDER __BYTE_ORDER +#elif defined(SDL_PLATFORM_SOLARIS) +#include +#if defined(_LITTLE_ENDIAN) +#define SDL_BYTEORDER SDL_LIL_ENDIAN +#elif defined(_BIG_ENDIAN) +#define SDL_BYTEORDER SDL_BIG_ENDIAN +#else +#error Unsupported endianness +#endif +#elif defined(SDL_PLATFORM_OPENBSD) || defined(__DragonFly__) +#include +#define SDL_BYTEORDER BYTE_ORDER +#elif defined(SDL_PLATFORM_FREEBSD) || defined(SDL_PLATFORM_NETBSD) +#include +#define SDL_BYTEORDER BYTE_ORDER +/* predefs from newer gcc and clang versions: */ +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__BYTE_ORDER__) +#if (__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__) +#define SDL_BYTEORDER SDL_LIL_ENDIAN +#elif (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__) +#define SDL_BYTEORDER SDL_BIG_ENDIAN +#else +#error Unsupported endianness +#endif /**/ +#else +#if defined(__hppa__) || \ + defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \ + (defined(__MIPS__) && defined(__MIPSEB__)) || \ + defined(__ppc__) || defined(__POWERPC__) || defined(__powerpc__) || defined(__PPC__) || \ + defined(__sparc__) || defined(__sparc) +#define SDL_BYTEORDER SDL_BIG_ENDIAN +#else +#define SDL_BYTEORDER SDL_LIL_ENDIAN +#endif +#endif /* SDL_PLATFORM_LINUX */ +#endif /* !SDL_BYTEORDER */ + +#ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +/* predefs from newer gcc versions: */ +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN +#elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) +#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN +#else +#error Unsupported endianness +#endif /**/ +#elif defined(__MAVERICK__) +/* For Maverick, float words are always little-endian. */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN +#elif (defined(__arm__) || defined(__thumb__)) && !defined(__VFP_FP__) && !defined(__ARM_EABI__) +/* For FPA, float words are always big-endian. */ +#define SDL_FLOATWORDORDER SDL_BIG_ENDIAN +#else +/* By default, assume that floats words follow the memory system mode. */ +#define SDL_FLOATWORDORDER SDL_BYTEORDER +#endif /* __FLOAT_WORD_ORDER__ */ +#endif /* !SDL_FLOATWORDORDER */ + + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* various modern compilers may have builtin swap */ +#if defined(__GNUC__) || defined(__clang__) +# define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ + (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8)) +# define HAS_BUILTIN_BSWAP32 (SDL_HAS_BUILTIN(__builtin_bswap32)) || \ + (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) +# define HAS_BUILTIN_BSWAP64 (SDL_HAS_BUILTIN(__builtin_bswap64)) || \ + (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) + + /* this one is broken */ +# define HAS_BROKEN_BSWAP (__GNUC__ == 2 && __GNUC_MINOR__ <= 95) +#else +# define HAS_BUILTIN_BSWAP16 0 +# define HAS_BUILTIN_BSWAP32 0 +# define HAS_BUILTIN_BSWAP64 0 +# define HAS_BROKEN_BSWAP 0 +#endif + +/* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +#if HAS_BUILTIN_BSWAP16 +#define SDL_Swap16(x) __builtin_bswap16(x) +#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) +#pragma intrinsic(_byteswap_ushort) +#define SDL_Swap16(x) _byteswap_ushort(x) +#elif defined(__i386__) && !HAS_BROKEN_BSWAP +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) +{ + __asm__("xchgb %b0,%h0": "=q"(x):"0"(x)); + return x; +} +#elif defined(__x86_64__) +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) +{ + __asm__("xchgb %b0,%h0": "=Q"(x):"0"(x)); + return x; +} +#elif (defined(__powerpc__) || defined(__ppc__)) +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) +{ + int result; + + __asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x)); + return (Uint16)result; +} +#elif (defined(__m68k__) && !defined(__mcoldfire__)) +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) +{ + __asm__("rorw #8,%0": "=d"(x): "0"(x):"cc"); + return x; +} +#elif defined(__WATCOMC__) && defined(__386__) +extern __inline Uint16 SDL_Swap16(Uint16); +#pragma aux SDL_Swap16 = \ + "xchg al, ah" \ + parm [ax] \ + modify [ax]; +#else +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) +{ + return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); +} +#endif +#endif + +/* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +#if HAS_BUILTIN_BSWAP32 +#define SDL_Swap32(x) __builtin_bswap32(x) +#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) +#pragma intrinsic(_byteswap_ulong) +#define SDL_Swap32(x) _byteswap_ulong(x) +#elif defined(__i386__) && !HAS_BROKEN_BSWAP +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) +{ + __asm__("bswap %0": "=r"(x):"0"(x)); + return x; +} +#elif defined(__x86_64__) +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) +{ + __asm__("bswapl %0": "=r"(x):"0"(x)); + return x; +} +#elif (defined(__powerpc__) || defined(__ppc__)) +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) +{ + Uint32 result; + + __asm__("rlwimi %0,%2,24,16,23": "=&r"(result): "0" (x>>24), "r"(x)); + __asm__("rlwimi %0,%2,8,8,15" : "=&r"(result): "0" (result), "r"(x)); + __asm__("rlwimi %0,%2,24,0,7" : "=&r"(result): "0" (result), "r"(x)); + return result; +} +#elif (defined(__m68k__) && !defined(__mcoldfire__)) +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) +{ + __asm__("rorw #8,%0\n\tswap %0\n\trorw #8,%0": "=d"(x): "0"(x):"cc"); + return x; +} +#elif defined(__WATCOMC__) && defined(__386__) +extern __inline Uint32 SDL_Swap32(Uint32); +#pragma aux SDL_Swap32 = \ + "bswap eax" \ + parm [eax] \ + modify [eax]; +#else +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) +{ + return SDL_static_cast(Uint32, ((x << 24) | ((x << 8) & 0x00FF0000) | + ((x >> 8) & 0x0000FF00) | (x >> 24))); +} +#endif +#endif + +/* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +#if HAS_BUILTIN_BSWAP64 +#define SDL_Swap64(x) __builtin_bswap64(x) +#elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) +#pragma intrinsic(_byteswap_uint64) +#define SDL_Swap64(x) _byteswap_uint64(x) +#elif defined(__i386__) && !HAS_BROKEN_BSWAP +SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) +{ + union { + struct { + Uint32 a, b; + } s; + Uint64 u; + } v; + v.u = x; + __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1" + : "=r"(v.s.a), "=r"(v.s.b) + : "0" (v.s.a), "1"(v.s.b)); + return v.u; +} +#elif defined(__x86_64__) +SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) +{ + __asm__("bswapq %0": "=r"(x):"0"(x)); + return x; +} +#elif defined(__WATCOMC__) && defined(__386__) +extern __inline Uint64 SDL_Swap64(Uint64); +#pragma aux SDL_Swap64 = \ + "bswap eax" \ + "bswap edx" \ + "xchg eax,edx" \ + parm [eax edx] \ + modify [eax edx]; +#else +SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) +{ + Uint32 hi, lo; + + /* Separate into high and low 32-bit values and swap them */ + lo = SDL_static_cast(Uint32, x & 0xFFFFFFFF); + x >>= 32; + hi = SDL_static_cast(Uint32, x & 0xFFFFFFFF); + x = SDL_Swap32(lo); + x <<= 32; + x |= SDL_Swap32(hi); + return (x); +} +#endif +#endif + +/** + * Byte-swap a floating point number. + * + * This will always byte-swap the value, whether it's currently in the native + * byteorder of the system or not. You should use SDL_SwapFloatLE or + * SDL_SwapFloatBE instead, in most cases. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the value to byte-swap. + * \returns x, with its bytes in the opposite endian order. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE float SDL_SwapFloat(float x) +{ + union { + float f; + Uint32 ui32; + } swapper; + swapper.f = x; + swapper.ui32 = SDL_Swap32(swapper.ui32); + return swapper.f; +} + +/* remove extra macros */ +#undef HAS_BROKEN_BSWAP +#undef HAS_BUILTIN_BSWAP16 +#undef HAS_BUILTIN_BSWAP32 +#undef HAS_BUILTIN_BSWAP64 + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Byte-swap an unsigned 16-bit number. + * + * This will always byte-swap the value, whether it's currently in the native + * byteorder of the system or not. You should use SDL_Swap16LE or SDL_Swap16BE + * instead, in most cases. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the value to byte-swap. + * \returns `x`, with its bytes in the opposite endian order. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } + +/** + * Byte-swap an unsigned 32-bit number. + * + * This will always byte-swap the value, whether it's currently in the native + * byteorder of the system or not. You should use SDL_Swap32LE or SDL_Swap32BE + * instead, in most cases. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the value to byte-swap. + * \returns `x`, with its bytes in the opposite endian order. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } + +/** + * Byte-swap an unsigned 64-bit number. + * + * This will always byte-swap the value, whether it's currently in the native + * byteorder of the system or not. You should use SDL_Swap64LE or SDL_Swap64BE + * instead, in most cases. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the value to byte-swap. + * \returns `x`, with its bytes in the opposite endian order. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } + +/** + * Swap a 16-bit value from littleendian to native byte order. + * + * If this is running on a littleendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in littleendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a 32-bit value from littleendian to native byte order. + * + * If this is running on a littleendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in littleendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a 64-bit value from littleendian to native byte order. + * + * If this is running on a littleendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in littleendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a floating point value from littleendian to native byte order. + * + * If this is running on a littleendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in littleendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a 16-bit value from bigendian to native byte order. + * + * If this is running on a bigendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in bigendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a 32-bit value from bigendian to native byte order. + * + * If this is running on a bigendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in bigendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a 64-bit value from bigendian to native byte order. + * + * If this is running on a bigendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in bigendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) + +/** + * Swap a floating point value from bigendian to native byte order. + * + * If this is running on a bigendian system, `x` is returned unchanged. + * + * This macro never references `x` more than once, avoiding side effects. + * + * \param x the value to swap, in bigendian byte order. + * \returns `x` in native byte order. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) + +#elif SDL_BYTEORDER == SDL_LIL_ENDIAN +#define SDL_Swap16LE(x) (x) +#define SDL_Swap32LE(x) (x) +#define SDL_Swap64LE(x) (x) +#define SDL_SwapFloatLE(x) (x) +#define SDL_Swap16BE(x) SDL_Swap16(x) +#define SDL_Swap32BE(x) SDL_Swap32(x) +#define SDL_Swap64BE(x) SDL_Swap64(x) +#define SDL_SwapFloatBE(x) SDL_SwapFloat(x) +#else +#define SDL_Swap16LE(x) SDL_Swap16(x) +#define SDL_Swap32LE(x) SDL_Swap32(x) +#define SDL_Swap64LE(x) SDL_Swap64(x) +#define SDL_SwapFloatLE(x) SDL_SwapFloat(x) +#define SDL_Swap16BE(x) (x) +#define SDL_Swap32BE(x) (x) +#define SDL_Swap64BE(x) (x) +#define SDL_SwapFloatBE(x) (x) +#endif + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_endian_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_error.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_error.h new file mode 100644 index 0000000000..934967c1cf --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_error.h @@ -0,0 +1,226 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryError + * + * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. + */ + +#ifndef SDL_error_h_ +#define SDL_error_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* Public functions */ + + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: + * + * ```c + * if (error_code) { + * return SDL_SetError("This operation has failed: %d", error_code); + * } + * ``` + * + * \param fmt a printf()-style message format string. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetErrorV + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); + +/** + * Set an error indicating that memory allocation failed. + * + * This function does not do any memory allocation. + * + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); + +/** + * Retrieve a message about the last error that occurred on the current + * thread. + * + * It is possible for multiple errors to occur before calling SDL_GetError(). + * Only the last error is returned. + * + * The message is only applicable when an SDL function has signaled an error. + * You must check the return values of SDL function calls to determine when to + * appropriately call SDL_GetError(). You should *not* use the results of + * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set + * an error string even when reporting success. + * + * SDL will *not* clear the error string for successful API calls. You *must* + * check return values for failure cases before you can assume the error + * string applies. + * + * Error strings are set per-thread, so an error set in a different thread + * will not interfere with the current thread's operation. + * + * The returned value is a thread-local string which will remain valid until + * the current thread's error string is changed. The caller should make a copy + * if the value is needed after the next SDL API call. + * + * \returns a message with information about the specific error that occurred, + * or an empty string if there hasn't been an error message set since + * the last call to SDL_ClearError(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); + +/** + * Clear any previous error message for this thread. + * + * \returns true. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); + +/** + * \name Internal error functions + * + * \internal + * Private error reporting function - used internally. + */ +/* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + +/* @} *//* Internal error functions */ + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_error_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_events.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_events.h new file mode 100644 index 0000000000..d267f051f8 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_events.h @@ -0,0 +1,1576 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryEvents + * + * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. + */ + +#ifndef SDL_events_h_ +#define SDL_events_h_ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* General keyboard/mouse/pen state definitions */ + +/** + * The types of events that can be delivered. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_EventType +{ + SDL_EVENT_FIRST = 0, /**< Unused (do not remove) */ + + /* Application events */ + SDL_EVENT_QUIT = 0x100, /**< User-requested quit */ + + /* These application events have special meaning on iOS and Android, see README-ios.md and README-android.md for details */ + SDL_EVENT_TERMINATING, /**< The application is being terminated by the OS. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationWillTerminate() + Called on Android in onDestroy() + */ + SDL_EVENT_LOW_MEMORY, /**< The application is low on memory, free memory if possible. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationDidReceiveMemoryWarning() + Called on Android in onTrimMemory() + */ + SDL_EVENT_WILL_ENTER_BACKGROUND, /**< The application is about to enter the background. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationWillResignActive() + Called on Android in onPause() + */ + SDL_EVENT_DID_ENTER_BACKGROUND, /**< The application did enter the background and may not get CPU for some time. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationDidEnterBackground() + Called on Android in onPause() + */ + SDL_EVENT_WILL_ENTER_FOREGROUND, /**< The application is about to enter the foreground. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationWillEnterForeground() + Called on Android in onResume() + */ + SDL_EVENT_DID_ENTER_FOREGROUND, /**< The application is now interactive. This event must be handled in a callback set with SDL_AddEventWatch(). + Called on iOS in applicationDidBecomeActive() + Called on Android in onResume() + */ + + SDL_EVENT_LOCALE_CHANGED, /**< The user's locale preferences have changed. */ + + SDL_EVENT_SYSTEM_THEME_CHANGED, /**< The system theme changed */ + + /* Display events */ + /* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */ + SDL_EVENT_DISPLAY_ORIENTATION = 0x151, /**< Display orientation has changed to data1 */ + SDL_EVENT_DISPLAY_ADDED, /**< Display has been added to the system */ + SDL_EVENT_DISPLAY_REMOVED, /**< Display has been removed from the system */ + SDL_EVENT_DISPLAY_MOVED, /**< Display has changed position */ + SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED, /**< Display has changed desktop mode */ + SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED, /**< Display has changed current mode */ + SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, /**< Display has changed content scale */ + SDL_EVENT_DISPLAY_FIRST = SDL_EVENT_DISPLAY_ORIENTATION, + SDL_EVENT_DISPLAY_LAST = SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, + + /* Window events */ + /* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */ + /* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */ + SDL_EVENT_WINDOW_SHOWN = 0x202, /**< Window has been shown */ + SDL_EVENT_WINDOW_HIDDEN, /**< Window has been hidden */ + SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event */ + SDL_EVENT_WINDOW_MOVED, /**< Window has been moved to data1, data2 */ + SDL_EVENT_WINDOW_RESIZED, /**< Window has been resized to data1xdata2 */ + SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED,/**< The pixel size of the window has changed to data1xdata2 */ + SDL_EVENT_WINDOW_METAL_VIEW_RESIZED,/**< The pixel size of a Metal view associated with the window has changed */ + SDL_EVENT_WINDOW_MINIMIZED, /**< Window has been minimized */ + SDL_EVENT_WINDOW_MAXIMIZED, /**< Window has been maximized */ + SDL_EVENT_WINDOW_RESTORED, /**< Window has been restored to normal size and position */ + SDL_EVENT_WINDOW_MOUSE_ENTER, /**< Window has gained mouse focus */ + SDL_EVENT_WINDOW_MOUSE_LEAVE, /**< Window has lost mouse focus */ + SDL_EVENT_WINDOW_FOCUS_GAINED, /**< Window has gained keyboard focus */ + SDL_EVENT_WINDOW_FOCUS_LOST, /**< Window has lost keyboard focus */ + SDL_EVENT_WINDOW_CLOSE_REQUESTED, /**< The window manager requests that the window be closed */ + SDL_EVENT_WINDOW_HIT_TEST, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL */ + SDL_EVENT_WINDOW_ICCPROF_CHANGED, /**< The ICC profile of the window's display has changed */ + SDL_EVENT_WINDOW_DISPLAY_CHANGED, /**< Window has been moved to display data1 */ + SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, /**< Window display scale has been changed */ + SDL_EVENT_WINDOW_SAFE_AREA_CHANGED, /**< The window safe area has been changed */ + SDL_EVENT_WINDOW_OCCLUDED, /**< The window has been occluded */ + SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ + SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ + SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled + in an event watcher, the window handle is still valid and can still be used to retrieve any properties + associated with the window. Otherwise, the handle has already been destroyed and all resources + associated with it are invalid */ + SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ + SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN, + SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_HDR_STATE_CHANGED, + + /* Keyboard events */ + SDL_EVENT_KEY_DOWN = 0x300, /**< Key pressed */ + SDL_EVENT_KEY_UP, /**< Key released */ + SDL_EVENT_TEXT_EDITING, /**< Keyboard text editing (composition) */ + SDL_EVENT_TEXT_INPUT, /**< Keyboard text input */ + SDL_EVENT_KEYMAP_CHANGED, /**< Keymap changed due to a system event such as an + input language or keyboard layout change. */ + SDL_EVENT_KEYBOARD_ADDED, /**< A new keyboard has been inserted into the system */ + SDL_EVENT_KEYBOARD_REMOVED, /**< A keyboard has been removed */ + SDL_EVENT_TEXT_EDITING_CANDIDATES, /**< Keyboard text editing candidates */ + + /* Mouse events */ + SDL_EVENT_MOUSE_MOTION = 0x400, /**< Mouse moved */ + SDL_EVENT_MOUSE_BUTTON_DOWN, /**< Mouse button pressed */ + SDL_EVENT_MOUSE_BUTTON_UP, /**< Mouse button released */ + SDL_EVENT_MOUSE_WHEEL, /**< Mouse wheel motion */ + SDL_EVENT_MOUSE_ADDED, /**< A new mouse has been inserted into the system */ + SDL_EVENT_MOUSE_REMOVED, /**< A mouse has been removed */ + + /* Joystick events */ + SDL_EVENT_JOYSTICK_AXIS_MOTION = 0x600, /**< Joystick axis motion */ + SDL_EVENT_JOYSTICK_BALL_MOTION, /**< Joystick trackball motion */ + SDL_EVENT_JOYSTICK_HAT_MOTION, /**< Joystick hat position change */ + SDL_EVENT_JOYSTICK_BUTTON_DOWN, /**< Joystick button pressed */ + SDL_EVENT_JOYSTICK_BUTTON_UP, /**< Joystick button released */ + SDL_EVENT_JOYSTICK_ADDED, /**< A new joystick has been inserted into the system */ + SDL_EVENT_JOYSTICK_REMOVED, /**< An opened joystick has been removed */ + SDL_EVENT_JOYSTICK_BATTERY_UPDATED, /**< Joystick battery level change */ + SDL_EVENT_JOYSTICK_UPDATE_COMPLETE, /**< Joystick update is complete */ + + /* Gamepad events */ + SDL_EVENT_GAMEPAD_AXIS_MOTION = 0x650, /**< Gamepad axis motion */ + SDL_EVENT_GAMEPAD_BUTTON_DOWN, /**< Gamepad button pressed */ + SDL_EVENT_GAMEPAD_BUTTON_UP, /**< Gamepad button released */ + SDL_EVENT_GAMEPAD_ADDED, /**< A new gamepad has been inserted into the system */ + SDL_EVENT_GAMEPAD_REMOVED, /**< A gamepad has been removed */ + SDL_EVENT_GAMEPAD_REMAPPED, /**< The gamepad mapping was updated */ + SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, /**< Gamepad touchpad was touched */ + SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, /**< Gamepad touchpad finger was moved */ + SDL_EVENT_GAMEPAD_TOUCHPAD_UP, /**< Gamepad touchpad finger was lifted */ + SDL_EVENT_GAMEPAD_SENSOR_UPDATE, /**< Gamepad sensor was updated */ + SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, /**< Gamepad update is complete */ + SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED, /**< Gamepad Steam handle has changed */ + + /* Touch events */ + SDL_EVENT_FINGER_DOWN = 0x700, + SDL_EVENT_FINGER_UP, + SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, + + /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ + + /* Clipboard events */ + SDL_EVENT_CLIPBOARD_UPDATE = 0x900, /**< The clipboard or primary selection changed */ + + /* Drag and drop events */ + SDL_EVENT_DROP_FILE = 0x1000, /**< The system requests a file open */ + SDL_EVENT_DROP_TEXT, /**< text/plain drag-and-drop event */ + SDL_EVENT_DROP_BEGIN, /**< A new set of drops is beginning (NULL filename) */ + SDL_EVENT_DROP_COMPLETE, /**< Current set of drops is now complete (NULL filename) */ + SDL_EVENT_DROP_POSITION, /**< Position while moving over the window */ + + /* Audio hotplug events */ + SDL_EVENT_AUDIO_DEVICE_ADDED = 0x1100, /**< A new audio device is available */ + SDL_EVENT_AUDIO_DEVICE_REMOVED, /**< An audio device has been removed. */ + SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED, /**< An audio device's format has been changed by the system. */ + + /* Sensor events */ + SDL_EVENT_SENSOR_UPDATE = 0x1200, /**< A sensor was updated */ + + /* Pressure-sensitive pen events */ + SDL_EVENT_PEN_PROXIMITY_IN = 0x1300, /**< Pressure-sensitive pen has become available */ + SDL_EVENT_PEN_PROXIMITY_OUT, /**< Pressure-sensitive pen has become unavailable */ + SDL_EVENT_PEN_DOWN, /**< Pressure-sensitive pen touched drawing surface */ + SDL_EVENT_PEN_UP, /**< Pressure-sensitive pen stopped touching drawing surface */ + SDL_EVENT_PEN_BUTTON_DOWN, /**< Pressure-sensitive pen button pressed */ + SDL_EVENT_PEN_BUTTON_UP, /**< Pressure-sensitive pen button released */ + SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen is moving on the tablet */ + SDL_EVENT_PEN_AXIS, /**< Pressure-sensitive pen angle/pressure/etc changed */ + + /* Camera hotplug events */ + SDL_EVENT_CAMERA_DEVICE_ADDED = 0x1400, /**< A new camera device is available */ + SDL_EVENT_CAMERA_DEVICE_REMOVED, /**< A camera device has been removed. */ + SDL_EVENT_CAMERA_DEVICE_APPROVED, /**< A camera device has been approved for use by the user. */ + SDL_EVENT_CAMERA_DEVICE_DENIED, /**< A camera device has been denied for use by the user. */ + + /* Render events */ + SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ + SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, + + /* Internal events */ + SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ + + /** Events SDL_EVENT_USER through SDL_EVENT_LAST are for your use, + * and should be allocated with SDL_RegisterEvents() + */ + SDL_EVENT_USER = 0x8000, + + /** + * This last event is only for bounding internal arrays + */ + SDL_EVENT_LAST = 0xFFFF, + + /* This just makes sure the enum is the size of Uint32 */ + SDL_EVENT_ENUM_PADDING = 0x7FFFFFFF + +} SDL_EventType; + +/** + * Fields shared by every event + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_CommonEvent +{ + Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ +} SDL_CommonEvent; + +/** + * Display state change event data (event.display.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_DisplayEvent +{ + SDL_EventType type; /**< SDL_DISPLAYEVENT_* */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_DisplayID displayID;/**< The associated display */ + Sint32 data1; /**< event dependent data */ + Sint32 data2; /**< event dependent data */ +} SDL_DisplayEvent; + +/** + * Window state change event data (event.window.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_WindowEvent +{ + SDL_EventType type; /**< SDL_EVENT_WINDOW_* */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The associated window */ + Sint32 data1; /**< event dependent data */ + Sint32 data2; /**< event dependent data */ +} SDL_WindowEvent; + +/** + * Keyboard device event structure (event.kdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_KeyboardDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_KEYBOARD_ADDED or SDL_EVENT_KEYBOARD_REMOVED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_KeyboardID which; /**< The keyboard instance id */ +} SDL_KeyboardDeviceEvent; + +/** + * Keyboard button event structure (event.key.*) + * + * The `key` is the base SDL_Keycode generated by pressing the `scancode` + * using the current keyboard layout, applying any options specified in + * SDL_HINT_KEYCODE_OPTIONS. You can get the SDL_Keycode corresponding to the + * event scancode and modifiers directly from the keyboard layout, bypassing + * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetKeyFromScancode + * \sa SDL_HINT_KEYCODE_OPTIONS + */ +typedef struct SDL_KeyboardEvent +{ + SDL_EventType type; /**< SDL_EVENT_KEY_DOWN or SDL_EVENT_KEY_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with keyboard focus, if any */ + SDL_KeyboardID which; /**< The keyboard instance id, or 0 if unknown or virtual */ + SDL_Scancode scancode; /**< SDL physical key code */ + SDL_Keycode key; /**< SDL virtual key code */ + SDL_Keymod mod; /**< current key modifiers */ + Uint16 raw; /**< The platform dependent scancode for this event */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ +} SDL_KeyboardEvent; + +/** + * Keyboard text editing event structure (event.edit.*) + * + * The start cursor is the position, in UTF-8 characters, where new typing + * will be inserted into the editing text. The length is the number of UTF-8 + * characters that will be replaced by new typing. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TextEditingEvent +{ + SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with keyboard focus, if any */ + const char *text; /**< The editing text */ + Sint32 start; /**< The start cursor of selected editing text, or -1 if not set */ + Sint32 length; /**< The length of selected editing text, or -1 if not set */ +} SDL_TextEditingEvent; + +/** + * Keyboard IME candidates event structure (event.edit_candidates.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TextEditingCandidatesEvent +{ + SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING_CANDIDATES */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with keyboard focus, if any */ + const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ + Sint32 num_candidates; /**< The number of strings in `candidates` */ + Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_TextEditingCandidatesEvent; + +/** + * Keyboard text input event structure (event.text.*) + * + * This event will never be delivered unless text input is enabled by calling + * SDL_StartTextInput(). Text input is disabled by default! + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput + */ +typedef struct SDL_TextInputEvent +{ + SDL_EventType type; /**< SDL_EVENT_TEXT_INPUT */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with keyboard focus, if any */ + const char *text; /**< The input text, UTF-8 encoded */ +} SDL_TextInputEvent; + +/** + * Mouse device event structure (event.mdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_MouseDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_MOUSE_ADDED or SDL_EVENT_MOUSE_REMOVED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_MouseID which; /**< The mouse instance id */ +} SDL_MouseDeviceEvent; + +/** + * Mouse motion event structure (event.motion.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_MouseMotionEvent +{ + SDL_EventType type; /**< SDL_EVENT_MOUSE_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ + SDL_MouseButtonFlags state; /**< The current button state */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + float xrel; /**< The relative motion in the X direction */ + float yrel; /**< The relative motion in the Y direction */ +} SDL_MouseMotionEvent; + +/** + * Mouse button event structure (event.button.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_MouseButtonEvent +{ + SDL_EventType type; /**< SDL_EVENT_MOUSE_BUTTON_DOWN or SDL_EVENT_MOUSE_BUTTON_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ + Uint8 button; /**< The mouse button index */ + bool down; /**< true if the button is pressed */ + Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ + Uint8 padding; + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ +} SDL_MouseButtonEvent; + +/** + * Mouse wheel event structure (event.wheel.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_MouseWheelEvent +{ + SDL_EventType type; /**< SDL_EVENT_MOUSE_WHEEL */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ + float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ + float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ + SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ + float mouse_x; /**< X coordinate, relative to window */ + float mouse_y; /**< Y coordinate, relative to window */ + Sint32 integer_x; /**< The amount scrolled horizontally, accumulated to whole scroll "ticks" (added in 3.2.12) */ + Sint32 integer_y; /**< The amount scrolled vertically, accumulated to whole scroll "ticks" (added in 3.2.12) */ +} SDL_MouseWheelEvent; + +/** + * Joystick axis motion event structure (event.jaxis.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_JoyAxisEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_AXIS_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 axis; /**< The joystick axis index */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; + Sint16 value; /**< The axis value (range: -32768 to 32767) */ + Uint16 padding4; +} SDL_JoyAxisEvent; + +/** + * Joystick trackball motion event structure (event.jball.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_JoyBallEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BALL_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 ball; /**< The joystick trackball index */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; + Sint16 xrel; /**< The relative motion in the X direction */ + Sint16 yrel; /**< The relative motion in the Y direction */ +} SDL_JoyBallEvent; + +/** + * Joystick hat position change event structure (event.jhat.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_JoyHatEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_HAT_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 hat; /**< The joystick hat index */ + Uint8 value; /**< The hat position value. + * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP + * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT + * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN + * + * Note that zero means the POV is centered. + */ + Uint8 padding1; + Uint8 padding2; +} SDL_JoyHatEvent; + +/** + * Joystick button event structure (event.jbutton.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_JoyButtonEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BUTTON_DOWN or SDL_EVENT_JOYSTICK_BUTTON_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 button; /**< The joystick button index */ + bool down; /**< true if the button is pressed */ + Uint8 padding1; + Uint8 padding2; +} SDL_JoyButtonEvent; + +/** + * Joystick device event structure (event.jdevice.*) + * + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent + */ +typedef struct SDL_JoyDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_ADDED or SDL_EVENT_JOYSTICK_REMOVED or SDL_EVENT_JOYSTICK_UPDATE_COMPLETE */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ +} SDL_JoyDeviceEvent; + +/** + * Joystick battery level change event structure (event.jbattery.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_JoyBatteryEvent +{ + SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BATTERY_UPDATED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + SDL_PowerState state; /**< The joystick battery state */ + int percent; /**< The joystick battery percent charge remaining */ +} SDL_JoyBatteryEvent; + +/** + * Gamepad axis motion event structure (event.gaxis.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_GamepadAxisEvent +{ + SDL_EventType type; /**< SDL_EVENT_GAMEPAD_AXIS_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 axis; /**< The gamepad axis (SDL_GamepadAxis) */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; + Sint16 value; /**< The axis value (range: -32768 to 32767) */ + Uint16 padding4; +} SDL_GamepadAxisEvent; + + +/** + * Gamepad button event structure (event.gbutton.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_GamepadButtonEvent +{ + SDL_EventType type; /**< SDL_EVENT_GAMEPAD_BUTTON_DOWN or SDL_EVENT_GAMEPAD_BUTTON_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ + bool down; /**< true if the button is pressed */ + Uint8 padding1; + Uint8 padding2; +} SDL_GamepadButtonEvent; + + +/** + * Gamepad device event structure (event.gdevice.*) + * + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent + */ +typedef struct SDL_GamepadDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_GAMEPAD_ADDED, SDL_EVENT_GAMEPAD_REMOVED, or SDL_EVENT_GAMEPAD_REMAPPED, SDL_EVENT_GAMEPAD_UPDATE_COMPLETE or SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ +} SDL_GamepadDeviceEvent; + +/** + * Gamepad touchpad event structure (event.gtouchpad.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_GamepadTouchpadEvent +{ + SDL_EventType type; /**< SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN or SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION or SDL_EVENT_GAMEPAD_TOUCHPAD_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Sint32 touchpad; /**< The index of the touchpad */ + Sint32 finger; /**< The index of the finger on the touchpad */ + float x; /**< Normalized in the range 0...1 with 0 being on the left */ + float y; /**< Normalized in the range 0...1 with 0 being at the top */ + float pressure; /**< Normalized in the range 0...1 */ +} SDL_GamepadTouchpadEvent; + +/** + * Gamepad sensor event structure (event.gsensor.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_GamepadSensorEvent +{ + SDL_EventType type; /**< SDL_EVENT_GAMEPAD_SENSOR_UPDATE */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_JoystickID which; /**< The joystick instance id */ + Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */ + float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ + Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */ +} SDL_GamepadSensorEvent; + +/** + * Audio device event structure (event.adevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AudioDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_AUDIO_DEVICE_ADDED, or SDL_EVENT_AUDIO_DEVICE_REMOVED, or SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ + bool recording; /**< false if a playback device, true if a recording device. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_AudioDeviceEvent; + +/** + * Camera device event structure (event.cdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_CameraDeviceEvent +{ + SDL_EventType type; /**< SDL_EVENT_CAMERA_DEVICE_ADDED, SDL_EVENT_CAMERA_DEVICE_REMOVED, SDL_EVENT_CAMERA_DEVICE_APPROVED, SDL_EVENT_CAMERA_DEVICE_DENIED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ +} SDL_CameraDeviceEvent; + + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + +/** + * Touch finger event structure (event.tfinger.*) + * + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TouchFingerEvent +{ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_TouchID touchID; /**< The touch device id */ + SDL_FingerID fingerID; + float x; /**< Normalized in the range 0...1 */ + float y; /**< Normalized in the range 0...1 */ + float dx; /**< Normalized in the range -1...1 */ + float dy; /**< Normalized in the range -1...1 */ + float pressure; /**< Normalized in the range 0...1 */ + SDL_WindowID windowID; /**< The window underneath the finger, if any */ +} SDL_TouchFingerEvent; + +/** + * Pressure-sensitive pen proximity event structure (event.pmotion.*) + * + * When a pen becomes visible to the system (it is close enough to a tablet, + * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's + * ID. This ID is valid until the pen leaves proximity again (has been removed + * from the tablet's area, the tablet has been unplugged, etc). If the same + * pen reenters proximity again, it will be given a new ID. + * + * Note that "proximity" means "close enough for the tablet to know the tool + * is there." The pen touching and lifting off from the tablet while not + * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PenProximityEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ + SDL_PenID which; /**< The pen instance id */ +} SDL_PenProximityEvent; + +/** + * Pressure-sensitive pen motion event structure (event.pmotion.*) + * + * Depending on the hardware, you may get motion events when the pen is not + * touching a tablet, for tracking a pen even when it isn't drawing. You + * should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check + * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when + * dealing with pen motion. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PenMotionEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ +} SDL_PenMotionEvent; + +/** + * Pressure-sensitive pen touched event structure (event.ptouch.*) + * + * These events come when a pen touches a surface (a tablet, etc), or lifts + * off from one. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PenTouchEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_DOWN or SDL_EVENT_PEN_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ +} SDL_PenTouchEvent; + +/** + * Pressure-sensitive pen button event structure (event.pbutton.*) + * + * This is for buttons on the pen itself that the user might click. The pen + * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PenButtonEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + Uint8 button; /**< The pen button index (first button is 1). */ + bool down; /**< true if the button is pressed */ +} SDL_PenButtonEvent; + +/** + * Pressure-sensitive pen pressure / angle event structure (event.paxis.*) + * + * You might get some of these events even if the pen isn't touching the + * tablet. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PenAxisEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_AXIS */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + SDL_PenAxis axis; /**< Axis that has changed */ + float value; /**< New value of axis */ +} SDL_PenAxisEvent; + +/** + * An event used to drop text or request a file open by the system + * (event.drop.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_DropEvent +{ + SDL_EventType type; /**< SDL_EVENT_DROP_BEGIN or SDL_EVENT_DROP_FILE or SDL_EVENT_DROP_TEXT or SDL_EVENT_DROP_COMPLETE or SDL_EVENT_DROP_POSITION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window that was dropped on, if any */ + float x; /**< X coordinate, relative to window (not on begin) */ + float y; /**< Y coordinate, relative to window (not on begin) */ + const char *source; /**< The source app that sent this drop event, or NULL if that isn't available */ + const char *data; /**< The text for SDL_EVENT_DROP_TEXT and the file name for SDL_EVENT_DROP_FILE, NULL for other events */ +} SDL_DropEvent; + +/** + * An event triggered when the clipboard contents have changed + * (event.clipboard.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_ClipboardEvent +{ + SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ +} SDL_ClipboardEvent; + +/** + * Sensor event structure (event.sensor.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_SensorEvent +{ + SDL_EventType type; /**< SDL_EVENT_SENSOR_UPDATE */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_SensorID which; /**< The instance ID of the sensor */ + float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_GetSensorData() */ + Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */ +} SDL_SensorEvent; + +/** + * The "quit requested" event + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_QuitEvent +{ + SDL_EventType type; /**< SDL_EVENT_QUIT */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ +} SDL_QuitEvent; + +/** + * A user-defined event type (event.user.*) + * + * This event is unique; it is never created by SDL, but only by the + * application. The event can be pushed onto the event queue using + * SDL_PushEvent(). The contents of the structure members are completely up to + * the programmer; the only requirement is that '''type''' is a value obtained + * from SDL_RegisterEvents(). + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_UserEvent +{ + Uint32 type; /**< SDL_EVENT_USER through SDL_EVENT_LAST-1, Uint32 because these are not in the SDL_EventType enumeration */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The associated window if any */ + Sint32 code; /**< User defined event code */ + void *data1; /**< User defined data pointer */ + void *data2; /**< User defined data pointer */ +} SDL_UserEvent; + + +/** + * The structure for all events in SDL. + * + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef union SDL_Event +{ + Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */ + SDL_CommonEvent common; /**< Common event data */ + SDL_DisplayEvent display; /**< Display event data */ + SDL_WindowEvent window; /**< Window event data */ + SDL_KeyboardDeviceEvent kdevice; /**< Keyboard device change event data */ + SDL_KeyboardEvent key; /**< Keyboard event data */ + SDL_TextEditingEvent edit; /**< Text editing event data */ + SDL_TextEditingCandidatesEvent edit_candidates; /**< Text editing candidates event data */ + SDL_TextInputEvent text; /**< Text input event data */ + SDL_MouseDeviceEvent mdevice; /**< Mouse device change event data */ + SDL_MouseMotionEvent motion; /**< Mouse motion event data */ + SDL_MouseButtonEvent button; /**< Mouse button event data */ + SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */ + SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */ + SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */ + SDL_JoyBallEvent jball; /**< Joystick ball event data */ + SDL_JoyHatEvent jhat; /**< Joystick hat event data */ + SDL_JoyButtonEvent jbutton; /**< Joystick button event data */ + SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */ + SDL_GamepadDeviceEvent gdevice; /**< Gamepad device event data */ + SDL_GamepadAxisEvent gaxis; /**< Gamepad axis event data */ + SDL_GamepadButtonEvent gbutton; /**< Gamepad button event data */ + SDL_GamepadTouchpadEvent gtouchpad; /**< Gamepad touchpad event data */ + SDL_GamepadSensorEvent gsensor; /**< Gamepad sensor event data */ + SDL_AudioDeviceEvent adevice; /**< Audio device event data */ + SDL_CameraDeviceEvent cdevice; /**< Camera device event data */ + SDL_SensorEvent sensor; /**< Sensor event data */ + SDL_QuitEvent quit; /**< Quit request event data */ + SDL_UserEvent user; /**< Custom event data */ + SDL_TouchFingerEvent tfinger; /**< Touch finger event data */ + SDL_PenProximityEvent pproximity; /**< Pen proximity event data */ + SDL_PenTouchEvent ptouch; /**< Pen tip touching event data */ + SDL_PenMotionEvent pmotion; /**< Pen motion event data */ + SDL_PenButtonEvent pbutton; /**< Pen button event data */ + SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ + SDL_DropEvent drop; /**< Drag and drop event data */ + SDL_ClipboardEvent clipboard; /**< Clipboard event data */ + + /* This is necessary for ABI compatibility between Visual C++ and GCC. + Visual C++ will respect the push pack pragma and use 52 bytes (size of + SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit + architectures) for this union, and GCC will use the alignment of the + largest datatype within the union, which is 8 bytes on 64-bit + architectures. + + So... we'll add padding to force the size to be the same for both. + + On architectures where pointers are 16 bytes, this needs rounding up to + the next multiple of 16, 64, and on architectures where pointers are + even larger the size of SDL_UserEvent will dominate as being 3 pointers. + */ + Uint8 padding[128]; +} SDL_Event; + +/* Make sure we haven't broken binary compatibility */ +SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding)); + + +/* Function prototypes */ + +/** + * Pump the event loop, gathering events from the input devices. + * + * This function updates the event queue and internal input device state. + * + * SDL_PumpEvents() gathers all the pending input information from devices and + * places it in the event queue. Without calls to SDL_PumpEvents() no events + * would ever be placed on the queue. Often the need for calls to + * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and + * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not + * polling or waiting for events (e.g. you are filtering them), then you must + * call SDL_PumpEvents() to force an event queue update. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PollEvent + * \sa SDL_WaitEvent + */ +extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); + +/* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_EventAction +{ + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ +} SDL_EventAction; + +/** + * Check the event queue for messages and optionally return them. + * + * `action` may be any of the following: + * + * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the + * event queue. + * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, + * within the specified minimum and maximum type, will be returned to the + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. + * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, + * within the specified minimum and maximum type, will be returned to the + * caller and will be removed from the queue. + * + * You may have to call SDL_PumpEvents() before calling this function. + * Otherwise, the events may not be ready to be filtered when you call + * SDL_PeepEvents(). + * + * \param events destination buffer for the retrieved events, may be NULL to + * leave the events in the queue and return the number of events + * that would have been stored. + * \param numevents if action is SDL_ADDEVENT, the number of events to add + * back to the event queue; if action is SDL_PEEKEVENT or + * SDL_GETEVENT, the maximum number of events to retrieve. + * \param action action to take; see [Remarks](#remarks) for details. + * \param minType minimum value of the event type to be considered; + * SDL_EVENT_FIRST is a safe choice. + * \param maxType maximum value of the event type to be considered; + * SDL_EVENT_LAST is a safe choice. + * \returns the number of events actually stored or -1 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PollEvent + * \sa SDL_PumpEvents + * \sa SDL_PushEvent + */ +extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_EventAction action, Uint32 minType, Uint32 maxType); +/* @} */ + +/** + * Check for the existence of a certain event type in the event queue. + * + * If you need to check for a range of event types, use SDL_HasEvents() + * instead. + * + * \param type the type of event to be queried; see SDL_EventType for details. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasEvents + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); + + +/** + * Check for the existence of certain event types in the event queue. + * + * If you need to check for a single event type, use SDL_HasEvent() instead. + * + * \param minType the low end of event type to be queried, inclusive; see + * SDL_EventType for details. + * \param maxType the high end of event type to be queried, inclusive; see + * SDL_EventType for details. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasEvents + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); + +/** + * Clear events of a specific type from the event queue. + * + * This will unconditionally remove any events from the queue that match + * `type`. If you need to remove a range of event types, use SDL_FlushEvents() + * instead. + * + * It's also normal to just ignore events you don't care about in your event + * loop without calling this function. + * + * This function only affects currently queued events. If you want to make + * sure that all pending OS events are flushed, you can call SDL_PumpEvents() + * on the main thread immediately before the flush call. + * + * If you have user events with custom data that needs to be freed, you should + * use SDL_PeepEvents() to remove and clean up those events before calling + * this function. + * + * \param type the type of event to be cleared; see SDL_EventType for details. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FlushEvents + */ +extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); + +/** + * Clear events of a range of types from the event queue. + * + * This will unconditionally remove any events from the queue that are in the + * range of `minType` to `maxType`, inclusive. If you need to remove a single + * event type, use SDL_FlushEvent() instead. + * + * It's also normal to just ignore events you don't care about in your event + * loop without calling this function. + * + * This function only affects currently queued events. If you want to make + * sure that all pending OS events are flushed, you can call SDL_PumpEvents() + * on the main thread immediately before the flush call. + * + * \param minType the low end of event type to be cleared, inclusive; see + * SDL_EventType for details. + * \param maxType the high end of event type to be cleared, inclusive; see + * SDL_EventType for details. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FlushEvent + */ +extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); + +/** + * Poll for currently pending events. + * + * If `event` is not NULL, the next event is removed from the queue and stored + * in the SDL_Event structure pointed to by `event`. The 1 returned refers to + * this event, immediately stored in the SDL Event structure -- not an event + * to follow. + * + * If `event` is NULL, it simply returns 1 if there is an event in the queue, + * but will not remove it from the queue. + * + * As this function may implicitly call SDL_PumpEvents(), you can only call + * this function in the thread that set the video mode. + * + * SDL_PollEvent() is the favored way of receiving system events since it can + * be done from the main loop and does not suspend the main loop while waiting + * on an event to be posted. + * + * The common practice is to fully process the event queue once every frame, + * usually as a first step before updating the game's state: + * + * ```c + * while (game_is_still_running) { + * SDL_Event event; + * while (SDL_PollEvent(&event)) { // poll until all events are handled! + * // decide what to do with this event. + * } + * + * // update game state, draw the current frame + * } + * ``` + * + * \param event the SDL_Event structure to be filled with the next event from + * the queue, or NULL. + * \returns true if this got an event or false if there are none available. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PushEvent + * \sa SDL_WaitEvent + * \sa SDL_WaitEventTimeout + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); + +/** + * Wait indefinitely for the next available event. + * + * If `event` is not NULL, the next event is removed from the queue and stored + * in the SDL_Event structure pointed to by `event`. + * + * As this function may implicitly call SDL_PumpEvents(), you can only call + * this function in the thread that initialized the video subsystem. + * + * \param event the SDL_Event structure to be filled in with the next event + * from the queue, or NULL. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PollEvent + * \sa SDL_PushEvent + * \sa SDL_WaitEventTimeout + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); + +/** + * Wait until the specified timeout (in milliseconds) for the next available + * event. + * + * If `event` is not NULL, the next event is removed from the queue and stored + * in the SDL_Event structure pointed to by `event`. + * + * As this function may implicitly call SDL_PumpEvents(), you can only call + * this function in the thread that initialized the video subsystem. + * + * The timeout is not guaranteed, the actual wait time could be longer due to + * system scheduling. + * + * \param event the SDL_Event structure to be filled in with the next event + * from the queue, or NULL. + * \param timeoutMS the maximum number of milliseconds to wait for the next + * available event. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PollEvent + * \sa SDL_PushEvent + * \sa SDL_WaitEvent + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); + +/** + * Add an event to the event queue. + * + * The event queue can actually be used as a two way communication channel. + * Not only can events be read from the queue, but the user can also push + * their own events onto it. `event` is a pointer to the event structure you + * wish to push onto the queue. The event is copied into the queue, and the + * caller may dispose of the memory pointed to after SDL_PushEvent() returns. + * + * Note: Pushing device input events onto the queue doesn't modify the state + * of the device within SDL. + * + * Note: Events pushed onto the queue with SDL_PushEvent() get passed through + * the event filter but events added with SDL_PeepEvents() do not. + * + * For pushing application-specific events, please use SDL_RegisterEvents() to + * get an event type that does not conflict with other code that also wants + * its own custom event types. + * + * \param event the SDL_Event to be added to the queue. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PeepEvents + * \sa SDL_PollEvent + * \sa SDL_RegisterEvents + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); + +/** + * A function pointer used for callbacks that watch the event queue. + * + * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or + * SDL_AddEventWatch, etc. + * \param event the event that triggered the callback. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. + * + * \threadsafety SDL may call this callback at any time from any thread; the + * application is responsible for locking resources the callback + * touches that need to be protected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetEventFilter + * \sa SDL_AddEventWatch + */ +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); + +/** + * Set up a filter to process all events before they are added to the internal + * event queue. + * + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. + * + * **WARNING**: Be very careful of what you do in the event filter function, + * as it may run in a different thread! + * + * On platforms that support it, if the quit event is generated by an + * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the + * application at the next event poll. + * + * Note: Disabled events never make it to the event filter function; see + * SDL_SetEventEnabled(). + * + * Note: Events pushed onto the queue with SDL_PushEvent() get passed through + * the event filter, but events pushed onto the queue with SDL_PeepEvents() do + * not. + * + * \param filter an SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + * \sa SDL_SetEventEnabled + * \sa SDL_GetEventFilter + * \sa SDL_PeepEvents + * \sa SDL_PushEvent + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void *userdata); + +/** + * Query the current event filter. + * + * This function can be used to "chain" filters, by saving the existing filter + * before replacing it with a function that will call that saved filter. + * + * \param filter the current callback function will be stored here. + * \param userdata the pointer that is passed to the current event filter will + * be stored here. + * \returns true on success or false if there is no event filter set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEventFilter + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); + +/** + * Add a callback to be triggered when an event is added to the event queue. + * + * `filter` will be called when an event happens, and its return value is + * ignored. + * + * **WARNING**: Be very careful of what you do in the event filter function, + * as it may run in a different thread! + * + * If the quit event is generated by a signal (e.g. SIGINT), it will bypass + * the internal queue and be delivered to the watch callback immediately, and + * arrive at the next event poll. + * + * Note: the callback is called for events posted by the user through + * SDL_PushEvent(), but not for disabled events, nor for events by a filter + * callback set with SDL_SetEventFilter(), nor for events posted by the user + * through SDL_PeepEvents(). + * + * \param filter an SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveEventWatch + * \sa SDL_SetEventFilter + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); + +/** + * Remove an event watch callback added with SDL_AddEventWatch(). + * + * This function takes the same input as SDL_AddEventWatch() to identify and + * delete the corresponding callback. + * + * \param filter the function originally passed to SDL_AddEventWatch(). + * \param userdata the pointer originally passed to SDL_AddEventWatch(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, void *userdata); + +/** + * Run a specific filter function on the current event queue, removing any + * events for which the filter returns false. + * + * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), + * this function does not change the filter permanently, it only uses the + * supplied filter until this function returns. + * + * \param filter the SDL_EventFilter function to call when an event happens. + * \param userdata a pointer that is passed to `filter`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEventFilter + * \sa SDL_SetEventFilter + */ +extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *userdata); + +/** + * Set the state of processing events by type. + * + * \param type the type of event; see SDL_EventType for details. + * \param enabled whether to process the event or not. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EventEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); + +/** + * Query the state of processing events by type. + * + * \param type the type of event; see SDL_EventType for details. + * \returns true if the event is being processed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEventEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); + +/** + * Allocate a set of user-defined events, and return the beginning event + * number for that set of events. + * + * \param numevents the number of events to be allocated. + * \returns the beginning event number, or 0 if numevents is invalid or if + * there are not enough user-defined events left. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PushEvent + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); + +/** + * Get window associated with an event. + * + * \param event an event containing a `windowID`. + * \returns the associated window on success or NULL if there is none. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PollEvent + * \sa SDL_WaitEvent + * \sa SDL_WaitEventTimeout + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromEvent(const SDL_Event *event); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_events_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_filesystem.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_filesystem.h new file mode 100644 index 0000000000..af3ca27e02 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_filesystem.h @@ -0,0 +1,503 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryFilesystem + * + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. + */ + +#ifndef SDL_filesystem_h_ +#define SDL_filesystem_h_ + +#include +#include + +#include + +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Get the directory where the application was run from. + * + * SDL caches the result of this call internally, but the first call to this + * function is not necessarily fast, so plan accordingly. + * + * **macOS and iOS Specific Functionality**: If the application is in a ".app" + * bundle, this function returns the Resource directory (e.g. + * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding + * a property to the Info.plist file. Adding a string key with the name + * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the + * behaviour. + * + * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an + * application in /Applications/SDLApp/MyApp.app): + * + * - `resource`: bundle resource directory (the default). For example: + * `/Applications/SDLApp/MyApp.app/Contents/Resources` + * - `bundle`: the Bundle directory. For example: + * `/Applications/SDLApp/MyApp.app/` + * - `parent`: the containing directory of the bundle. For example: + * `/Applications/SDLApp/` + * + * **Nintendo 3DS Specific Functionality**: This function returns "romfs" + * directory of the application as it is uncommon to store resources outside + * the executable. As such it is not a writable directory. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns an absolute path in UTF-8 encoding to the application data + * directory. NULL will be returned on error or when the platform + * doesn't implement this functionality, call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPrefPath + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); + +/** + * Get the user-and-app-specific path where files can be written. + * + * Get the "pref dir". This is meant to be where users can write personal + * files (preferences and save games, etc) that are specific to your + * application. This directory is unique per user, per application. + * + * This function will decide the appropriate location in the native + * filesystem, create the directory if necessary, and return a string of the + * absolute path to the directory in UTF-8 encoding. + * + * On Windows, the string might look like: + * + * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\` + * + * On Linux, the string might look like: + * + * `/home/bob/.local/share/My Program Name/` + * + * On macOS, the string might look like: + * + * `/Users/bob/Library/Application Support/My Program Name/` + * + * You should assume the path returned by this function is the only safe place + * to write files (and that SDL_GetBasePath(), while it might be writable, or + * even the parent of the returned path, isn't where you should be writing + * things). + * + * Both the org and app strings may become part of a directory name, so please + * follow these rules: + * + * - Try to use the same org string (_including case-sensitivity_) for all + * your applications that use this function. + * - Always use a unique app string for each one, and make sure it never + * changes for an app once you've decided on it. + * - Unicode characters are legal, as long as they are UTF-8 encoded, but... + * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game + * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \param org the name of your organization. + * \param app the name of your application. + * \returns a UTF-8 string of the user directory in platform-dependent + * notation. NULL if there's a problem (creating directory failed, + * etc.). This should be freed with SDL_free() when it is no longer + * needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetBasePath + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char *app); + +/** + * The type of the OS-provided default folder for a specific purpose. + * + * Note that the Trash folder isn't included here, because trashing files + * usually involves extra OS-specific functionality to remember the file's + * original location. + * + * The folders supported per platform are: + * + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | + * + * Note that on macOS/iOS, the Videos folder is called "Movies". + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetUserFolder + */ +typedef enum SDL_Folder +{ + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ +} SDL_Folder; + +/** + * Finds the most suitable user folder for a specific purpose. + * + * Many OSes provide certain standard folders for certain purposes, such as + * storing pictures, music or videos for a certain user. This function gives + * the path for many of those special locations. + * + * This function is specifically for _user_ folders, which are meant for the + * user to access and manage. For application-specific folders, meant to hold + * data for the application to manage, see SDL_GetBasePath() and + * SDL_GetPrefPath(). + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * If NULL is returned, the error may be obtained with SDL_GetError(). + * + * \param folder the type of folder to find. + * \returns either a null-terminated C string containing the full path to the + * folder, or NULL if an error happened. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); + + +/* Abstract filesystem interface */ + +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ +typedef enum SDL_PathType +{ + SDL_PATHTYPE_NONE, /**< path does not exist */ + SDL_PATHTYPE_FILE, /**< a normal file */ + SDL_PATHTYPE_DIRECTORY, /**< a directory */ + SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ +} SDL_PathType; + +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ +typedef struct SDL_PathInfo +{ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ +} SDL_PathInfo; + +/** + * Flags for path matching. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GlobDirectory + * \sa SDL_GlobStorageDirectory + */ +typedef Uint32 SDL_GlobFlags; + +#define SDL_GLOB_CASEINSENSITIVE (1u << 0) + +/** + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. + * + * \param path the path of the directory to create. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); + +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); + +/** + * Enumerate a directory through a callback function. + * + * This function provides every directory entry through an app-provided + * callback, called once for each directory entry, until all results have been + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * \param path the path of the directory to enumerate. + * \param callback a function that is called for each entry in the directory. + * \param userdata a pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); + +/** + * Remove a file or an empty directory. + * + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. + * + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); + +/** + * Rename a file or directory. + * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); + +/** + * Copy a file. + * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); + +/** + * Get information about a filesystem path. + * + * \param path the path to query. + * \param info a pointer filled in with information about the path, or NULL to + * check for the existence of a file. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); + +/** + * Enumerate a directory tree, filtered by pattern, and return a list. + * + * Files are filtered out if they don't match the string in `pattern`, which + * may contain wildcard characters '\*' (match everything) and '?' (match one + * character). If pattern is NULL, no filtering is done and all results are + * returned. Subdirectories are permitted, and are specified with a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path + * separator. + * + * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching + * case-insensitive. + * + * The returned array is always NULL-terminated, for your iterating + * convenience, but if `count` is non-NULL, on return it will contain the + * number of items in the array, not counting the NULL terminator. + * + * \param path the path of the directory to enumerate. + * \param pattern the pattern that files in the directory must match. Can be + * NULL. + * \param flags `SDL_GLOB_*` bitflags that affect this search. + * \param count on return, will be set to the number of items in the returned + * array. Can be NULL. + * \returns an array of strings on success or NULL on failure; call + * SDL_GetError() for more information. This is a single allocation + * that should be freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); + +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_filesystem_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gamepad.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gamepad.h new file mode 100644 index 0000000000..99f8b6593f --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gamepad.h @@ -0,0 +1,1509 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryGamepad + * + * SDL provides a low-level joystick API, which just treats joysticks as an + * arbitrary pile of buttons, axes, and hat switches. If you're planning to + * write your own control configuration screen, this can give you a lot of + * flexibility, but that's a lot of work, and most things that we consider + * "joysticks" now are actually console-style gamepads. So SDL provides the + * gamepad API on top of the lower-level joystick functionality. + * + * The difference between a joystick and a gamepad is that a gamepad tells you + * _where_ a button or axis is on the device. You don't speak to gamepads in + * terms of arbitrary numbers like "button 3" or "axis 2" but in standard + * locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or + * X/O/Square/Triangle, if you will). + * + * One turns a joystick into a gamepad by providing a magic configuration + * string, which tells SDL the details of a specific device: when you see this + * specific hardware, if button 2 gets pressed, this is actually D-Pad Up, + * etc. + * + * SDL has many popular controllers configured out of the box, and users can + * add their own controller details through an environment variable if it's + * otherwise unknown to SDL. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_GAMEPAD flag. This causes SDL to scan the system for gamepads, and + * load appropriate drivers. + * + * If you would like to receive gamepad updates while the application is in + * the background, you should set the following hint before calling + * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. + */ + +#ifndef SDL_gamepad_h_ +#define SDL_gamepad_h_ + +#include +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The structure used to identify an SDL gamepad + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Gamepad SDL_Gamepad; + +/** + * Standard gamepad types. + * + * This type does not necessarily map to first-party controllers from + * Microsoft/Sony/Nintendo; in many cases, third-party controllers can report + * as these, either because they were designed for a specific console, or they + * simply most closely match that console's controllers (does it have A/B/X/Y + * buttons or X/O/Square/Triangle? Does it have a touchpad? etc). + */ +typedef enum SDL_GamepadType +{ + SDL_GAMEPAD_TYPE_UNKNOWN = 0, + SDL_GAMEPAD_TYPE_STANDARD, + SDL_GAMEPAD_TYPE_XBOX360, + SDL_GAMEPAD_TYPE_XBOXONE, + SDL_GAMEPAD_TYPE_PS3, + SDL_GAMEPAD_TYPE_PS4, + SDL_GAMEPAD_TYPE_PS5, + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO, + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, + SDL_GAMEPAD_TYPE_COUNT +} SDL_GamepadType; + +/** + * The list of buttons available on a gamepad + * + * For controllers that use a diamond pattern for the face buttons, the + * south/east/west/north buttons below correspond to the locations in the + * diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo + * Switch controllers, this would be B/A/Y/X, for PlayStation controllers this + * would be Cross/Circle/Square/Triangle. + * + * For controllers that don't use a diamond pattern for the face buttons, the + * south/east/west/north buttons indicate the buttons labeled A, B, C, D, or + * 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary, + * secondary, etc. buttons. + * + * The activate action is often the south button and the cancel action is + * often the east button, but in some regions this is reversed, so your game + * should allow remapping actions based on user preferences. + * + * You can query the labels for the face buttons using + * SDL_GetGamepadButtonLabel() + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GamepadButton +{ + SDL_GAMEPAD_BUTTON_INVALID = -1, + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_BACK, + SDL_GAMEPAD_BUTTON_GUIDE, + SDL_GAMEPAD_BUTTON_START, + SDL_GAMEPAD_BUTTON_LEFT_STICK, + SDL_GAMEPAD_BUTTON_RIGHT_STICK, + SDL_GAMEPAD_BUTTON_LEFT_SHOULDER, + SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER, + SDL_GAMEPAD_BUTTON_DPAD_UP, + SDL_GAMEPAD_BUTTON_DPAD_DOWN, + SDL_GAMEPAD_BUTTON_DPAD_LEFT, + SDL_GAMEPAD_BUTTON_DPAD_RIGHT, + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT +} SDL_GamepadButton; + +/** + * The set of gamepad button labels + * + * This isn't a complete set, just the face buttons to make it easy to show + * button prompts. + * + * For a complete set, you should look at the button and gamepad type and have + * a set of symbols that work well with your art style. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GamepadButtonLabel +{ + SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN, + SDL_GAMEPAD_BUTTON_LABEL_A, + SDL_GAMEPAD_BUTTON_LABEL_B, + SDL_GAMEPAD_BUTTON_LABEL_X, + SDL_GAMEPAD_BUTTON_LABEL_Y, + SDL_GAMEPAD_BUTTON_LABEL_CROSS, + SDL_GAMEPAD_BUTTON_LABEL_CIRCLE, + SDL_GAMEPAD_BUTTON_LABEL_SQUARE, + SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE +} SDL_GamepadButtonLabel; + +/** + * The list of axes available on a gamepad + * + * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to + * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though + * advanced UI will allow users to set or autodetect the dead zone, which + * varies between gamepads. + * + * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully + * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the + * same range that will be reported by the lower-level SDL_GetJoystickAxis(). + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GamepadAxis +{ + SDL_GAMEPAD_AXIS_INVALID = -1, + SDL_GAMEPAD_AXIS_LEFTX, + SDL_GAMEPAD_AXIS_LEFTY, + SDL_GAMEPAD_AXIS_RIGHTX, + SDL_GAMEPAD_AXIS_RIGHTY, + SDL_GAMEPAD_AXIS_LEFT_TRIGGER, + SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, + SDL_GAMEPAD_AXIS_COUNT +} SDL_GamepadAxis; + +/** + * Types of gamepad control bindings. + * + * A gamepad is a collection of bindings that map arbitrary joystick buttons, + * axes and hat switches to specific positions on a generic console-style + * gamepad. This enum is used as part of SDL_GamepadBinding to specify those + * mappings. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GamepadBindingType +{ + SDL_GAMEPAD_BINDTYPE_NONE = 0, + SDL_GAMEPAD_BINDTYPE_BUTTON, + SDL_GAMEPAD_BINDTYPE_AXIS, + SDL_GAMEPAD_BINDTYPE_HAT +} SDL_GamepadBindingType; + +/** + * A mapping between one joystick input to a gamepad control. + * + * A gamepad has a collection of several bindings, to say, for example, when + * joystick button number 5 is pressed, that should be treated like the + * gamepad's "start" button. + * + * SDL has these bindings built-in for many popular controllers, and can add + * more with a simple text string. Those strings are parsed into a collection + * of these structs to make it easier to operate on the data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadBindings + */ +typedef struct SDL_GamepadBinding +{ + SDL_GamepadBindingType input_type; + union + { + int button; + + struct + { + int axis; + int axis_min; + int axis_max; + } axis; + + struct + { + int hat; + int hat_mask; + } hat; + + } input; + + SDL_GamepadBindingType output_type; + union + { + SDL_GamepadButton button; + + struct + { + SDL_GamepadAxis axis; + int axis_min; + int axis_max; + } axis; + + } output; +} SDL_GamepadBinding; + + +/** + * Add support for gamepads that SDL is unaware of or change the binding of an + * existing gamepad. + * + * The mapping string has the format "GUID,name,mapping", where GUID is the + * string value from SDL_GUIDToString(), name is the human readable string for + * the device and mappings are gamepad mappings to joystick ones. Under + * Windows there is a reserved GUID of "xinput" that covers all XInput + * devices. The mapping format for joystick is: + * + * - `bX`: a joystick button, index X + * - `hX.Y`: hat X with value Y + * - `aX`: axis X of the joystick + * + * Buttons can be used as a gamepad axes and vice versa. + * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * + * This string shows an example of a valid mapping for a gamepad: + * + * ```c + * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7" + * ``` + * + * \param mapping the mapping string. + * \returns 1 if a new mapping is added, 0 if an existing mapping is updated, + * -1 on failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + */ +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); + +/** + * Load a set of gamepad mappings from an SDL_IOStream. + * + * You can call this function several times, if needed, to load different + * database files. + * + * If a new mapping is loaded for an already known gamepad GUID, the later + * version will overwrite the one currently loaded. + * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * + * Mappings not belonging to the current platform or with no platform field + * specified will be ignored (i.e. mappings for Linux will be ignored in + * Windows, etc). + * + * This function will load the text database entirely in memory before + * processing it, so take this into consideration if you are in a memory + * constrained environment. + * + * \param src the data stream for the mappings to be added. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns the number of mappings added or -1 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + */ +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); + +/** + * Load a set of gamepad mappings from a file. + * + * You can call this function several times, if needed, to load different + * database files. + * + * If a new mapping is loaded for an already known gamepad GUID, the later + * version will overwrite the one currently loaded. + * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * + * Mappings not belonging to the current platform or with no platform field + * specified will be ignored (i.e. mappings for Linux will be ignored in + * Windows, etc). + * + * \param file the mappings file to load. + * \returns the number of mappings added or -1 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_AddGamepadMappingsFromIO + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + */ +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); + +/** + * Reinitialize the SDL mapping database to its initial state. + * + * This will generate gamepad events as needed if device mappings change. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); + +/** + * Get the current gamepad mappings. + * + * \param count a pointer filled in with the number of mappings returned, can + * be NULL. + * \returns an array of the mapping strings, NULL-terminated, or NULL on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); + +/** + * Get the gamepad mapping string for a given GUID. + * + * \param guid a structure containing the GUID for which a mapping is desired. + * \returns a mapping string or NULL on failure; call SDL_GetError() for more + * information. This should be freed with SDL_free() when it is no + * longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickGUIDForID + * \sa SDL_GetJoystickGUID + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); + +/** + * Get the current mapping of a gamepad. + * + * Details about mappings are discussed with SDL_AddGamepadMapping(). + * + * \param gamepad the gamepad you want to get the current mapping for. + * \returns a string that has the gamepad's mapping or NULL if no mapping is + * available; call SDL_GetError() for more information. This should + * be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_GetGamepadMappingForID + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_SetGamepadMapping + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); + +/** + * Set the current mapping of a joystick or gamepad. + * + * Details about mappings are discussed with SDL_AddGamepadMapping(). + * + * \param instance_id the joystick instance ID. + * \param mapping the mapping to use for this device, or NULL to clear the + * mapping. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_GetGamepadMapping + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); + +/** + * Return whether a gamepad is currently connected. + * + * \returns true if a gamepad is connected, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); + +/** + * Get a list of currently connected gamepads. + * + * \param count a pointer filled in with the number of gamepads returned, may + * be NULL. + * \returns a 0 terminated array of joystick instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasGamepad + * \sa SDL_OpenGamepad + */ +extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); + +/** + * Check if the given joystick is supported by the gamepad interface. + * + * \param instance_id the joystick instance ID. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoysticks + * \sa SDL_OpenGamepad + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); + +/** + * Get the implementation dependent name of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the name of the selected gamepad. If no name can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadName + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID instance_id); + +/** + * Get the implementation dependent path of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the path of the selected gamepad. If no path can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPath + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID instance_id); + +/** + * Get the player index of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the player index of a gamepad, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID instance_id); + +/** + * Get the implementation-dependent GUID of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the GUID of the selected gamepad. If called on an invalid index, + * this function returns a zero GUID. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GUIDToString + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID instance_id); + +/** + * Get the USB vendor ID of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the vendor ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB vendor ID of the selected gamepad. If called on an invalid + * index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadVendor + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID instance_id); + +/** + * Get the USB product ID of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the product ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB product ID of the selected gamepad. If called on an + * invalid index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProduct + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID instance_id); + +/** + * Get the product version of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the product version + * isn't available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the product version of the selected gamepad. If called on an + * invalid index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductVersion + * \sa SDL_GetGamepads + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_JoystickID instance_id); + +/** + * Get the type of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the gamepad type. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadType + * \sa SDL_GetGamepads + * \sa SDL_GetRealGamepadTypeForID + */ +extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_JoystickID instance_id); + +/** + * Get the type of a gamepad, ignoring any mapping override. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the gamepad type. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeForID + * \sa SDL_GetGamepads + * \sa SDL_GetRealGamepadType + */ +extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_JoystickID instance_id); + +/** + * Get the mapping of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the mapping string. Returns NULL if no mapping is available. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepads + * \sa SDL_GetGamepadMapping + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID instance_id); + +/** + * Open a gamepad for use. + * + * \param instance_id the joystick instance ID. + * \returns a gamepad identifier or NULL if an error occurred; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseGamepad + * \sa SDL_IsGamepad + */ +extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id); + +/** + * Get the SDL_Gamepad associated with a joystick instance ID, if it has been + * opened. + * + * \param instance_id the joystick instance ID of the gamepad. + * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been + * opened yet; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); + +/** + * Get the SDL_Gamepad associated with a player index. + * + * \param player_index the player index, which different from the instance ID. + * \returns the SDL_Gamepad associated with a player index. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + * \sa SDL_SetGamepadPlayerIndex + */ +extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int player_index); + +/** + * Get the properties associated with an opened gamepad. + * + * These properties are shared with the underlying joystick object. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN`: true if this gamepad has an LED + * that has adjustable brightness + * - `SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN`: true if this gamepad has an LED + * that has adjustable color + * - `SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN`: true if this gamepad has a + * player LED + * - `SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN`: true if this gamepad has + * left/right rumble + * - `SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this gamepad has + * simple trigger rumble + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); + +#define SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN +#define SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN +#define SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN +#define SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN +#define SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN + +/** + * Get the instance ID of an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the instance ID of the specified gamepad on success or 0 on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); + +/** + * Get the implementation-dependent name for an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the implementation dependent name for the gamepad, or NULL if + * there is no name or the identifier passed is invalid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadNameForID + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad); + +/** + * Get the implementation-dependent path for an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the implementation dependent path for the gamepad, or NULL if + * there is no path or the identifier passed is invalid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPathForID + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad); + +/** + * Get the type of an opened gamepad. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not + * available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeForID + */ +extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *gamepad); + +/** + * Get the type of an opened gamepad, ignoring any mapping override. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not + * available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRealGamepadTypeForID + */ +extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad *gamepad); + +/** + * Get the player index of an opened gamepad. + * + * For XInput gamepads this returns the XInput user index. + * + * \param gamepad the gamepad object to query. + * \returns the player index for gamepad, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadPlayerIndex + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); + +/** + * Set the player index of an opened gamepad. + * + * \param gamepad the gamepad object to adjust. + * \param player_index player index to assign to this gamepad, or -1 to clear + * the player index and turn off player LEDs. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); + +/** + * Get the USB vendor ID of an opened gamepad, if available. + * + * If the vendor ID isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB vendor ID, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadVendorForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); + +/** + * Get the USB product ID of an opened gamepad, if available. + * + * If the product ID isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB product ID, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); + +/** + * Get the product version of an opened gamepad, if available. + * + * If the product version isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB product version, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductVersionForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gamepad); + +/** + * Get the firmware version of an opened gamepad, if available. + * + * If the firmware version isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad firmware version, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); + +/** + * Get the serial number of an opened gamepad, if available. + * + * Returns the serial number of the gamepad, or NULL if it is not available. + * + * \param gamepad the gamepad object to query. + * \returns the serial number, or NULL if unavailable. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); + +/** + * Get the Steam Input handle of an opened gamepad, if available. + * + * Returns an InputHandle_t for the gamepad that can be used with Steam Input + * API: https://partner.steamgames.com/doc/api/ISteamInput + * + * \param gamepad the gamepad object to query. + * \returns the gamepad handle, or 0 if unavailable. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); + +/** + * Get the connection state of a gamepad. + * + * \param gamepad the gamepad object to query. + * \returns the connection state on success or + * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); + +/** + * Get the battery state of a gamepad. + * + * You should never take a battery status as absolute truth. Batteries + * (especially failing batteries) are delicate hardware, and the values + * reported here are best estimates based on what that hardware reports. It's + * not uncommon for older batteries to lose stored power much faster than it + * reports, or completely drain when reporting it has 20 percent left, etc. + * + * \param gamepad the gamepad object to query. + * \param percent a pointer filled in with the percentage of battery life + * left, between 0 and 100, or NULL to ignore. This will be + * filled in with -1 we can't determine a value or there is no + * battery. + * \returns the current battery state. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); + +/** + * Check if a gamepad has been opened and is currently connected. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); + +/** + * Get the underlying joystick from a gamepad. + * + * This function will give you a SDL_Joystick object, which allows you to use + * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful + * for getting a joystick's position at any given time, even if it hasn't + * moved (moving it would produce an event, which would have the axis' value). + * + * The pointer returned is owned by the SDL_Gamepad. You should not call + * SDL_CloseJoystick() on it, for example, since doing so will likely cause + * SDL to crash. + * + * \param gamepad the gamepad object that you want to get a joystick from. + * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); + +/** + * Set the state of gamepad event processing. + * + * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself + * and check the state of the gamepad when you want gamepad information. + * + * \param enabled whether to process gamepad events or not. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadEventsEnabled + * \sa SDL_UpdateGamepads + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); + +/** + * Query the state of gamepad event processing. + * + * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself + * and check the state of the gamepad when you want gamepad information. + * + * \returns true if gamepad events are being processed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadEventsEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); + +/** + * Get the SDL joystick layer bindings for a gamepad. + * + * \param gamepad a gamepad. + * \param count a pointer filled in with the number of bindings returned. + * \returns a NULL terminated array of pointers to bindings or NULL on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); + +/** + * Manually pump gamepad updates if not using the loop. + * + * This function is called automatically by the event loop if events are + * enabled. Under such circumstances, it will not be necessary to call this + * function. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); + +/** + * Convert a string into SDL_GamepadType enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * \param str string representing a SDL_GamepadType type. + * \returns the SDL_GamepadType enum corresponding to the input string, or + * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForType + */ +extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const char *str); + +/** + * Convert from an SDL_GamepadType enum to a string. + * + * \param type an enum value for a given SDL_GamepadType. + * \returns a string for the given type, or NULL if an invalid type is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeFromString + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_GamepadType type); + +/** + * Convert a string into SDL_GamepadAxis enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * Note specially that "righttrigger" and "lefttrigger" map to + * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`, + * respectively. + * + * \param str string representing a SDL_Gamepad axis. + * \returns the SDL_GamepadAxis enum corresponding to the input string, or + * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForAxis + */ +extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const char *str); + +/** + * Convert from an SDL_GamepadAxis enum to a string. + * + * \param axis an enum value for a given SDL_GamepadAxis. + * \returns a string for the given axis, or NULL if an invalid axis is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAxisFromString + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis axis); + +/** + * Query whether a gamepad has a given axis. + * + * This merely reports whether the gamepad's mapping defined this axis, as + * that is all the information SDL has about the physical device. + * + * \param gamepad a gamepad. + * \param axis an axis enum value (an SDL_GamepadAxis value). + * \returns true if the gamepad has this axis, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasButton + * \sa SDL_GetGamepadAxis + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); + +/** + * Get the current state of an axis control on a gamepad. + * + * The axis indices start at index 0. + * + * For thumbsticks, the state is a value ranging from -32768 (up/left) to + * 32767 (down/right). + * + * Triggers range from 0 when released to 32767 when fully pressed, and never + * return a negative value. Note that this differs from the value reported by + * the lower-level SDL_GetJoystickAxis(), which normally uses the full range. + * + * \param gamepad a gamepad. + * \param axis an axis index (one of the SDL_GamepadAxis values). + * \returns axis state (including 0) on success or 0 (also) on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasAxis + * \sa SDL_GetGamepadButton + */ +extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); + +/** + * Convert a string into an SDL_GamepadButton enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * \param str string representing a SDL_Gamepad axis. + * \returns the SDL_GamepadButton enum corresponding to the input string, or + * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForButton + */ +extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(const char *str); + +/** + * Convert from an SDL_GamepadButton enum to a string. + * + * \param button an enum value for a given SDL_GamepadButton. + * \returns a string for the given button, or NULL if an invalid button is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonFromString + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadButton button); + +/** + * Query whether a gamepad has a given button. + * + * This merely reports whether the gamepad's mapping defined this button, as + * that is all the information SDL has about the physical device. + * + * \param gamepad a gamepad. + * \param button a button enum value (an SDL_GamepadButton value). + * \returns true if the gamepad has this button, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasAxis + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); + +/** + * Get the current state of a button on a gamepad. + * + * \param gamepad a gamepad. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns true if the button is pressed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasButton + * \sa SDL_GetGamepadAxis + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); + +/** + * Get the label of a button on a gamepad. + * + * \param type the type of gamepad to check. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonLabel + */ +extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForType(SDL_GamepadType type, SDL_GamepadButton button); + +/** + * Get the label of a button on a gamepad. + * + * \param gamepad a gamepad. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonLabelForType + */ +extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL_Gamepad *gamepad, SDL_GamepadButton button); + +/** + * Get the number of touchpads on a gamepad. + * + * \param gamepad a gamepad. + * \returns number of touchpads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGamepadTouchpadFingers + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad); + +/** + * Get the number of supported simultaneous fingers on a touchpad on a game + * gamepad. + * + * \param gamepad a gamepad. + * \param touchpad a touchpad. + * \returns number of supported simultaneous fingers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTouchpadFinger + * \sa SDL_GetNumGamepadTouchpads + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepad, int touchpad); + +/** + * Get the current state of a finger on a touchpad on a gamepad. + * + * \param gamepad a gamepad. + * \param touchpad a touchpad. + * \param finger a finger. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGamepadTouchpadFingers + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); + +/** + * Return whether a gamepad has a particular sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns true if the sensor exists, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadSensorData + * \sa SDL_GetGamepadSensorDataRate + * \sa SDL_SetGamepadSensorEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); + +/** + * Set whether data reporting for a gamepad sensor is enabled. + * + * \param gamepad the gamepad to update. + * \param type the type of sensor to enable/disable. + * \param enabled whether data reporting should be enabled. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasSensor + * \sa SDL_GamepadSensorEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); + +/** + * Query whether sensor data reporting is enabled for a gamepad. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns true if the sensor is enabled, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadSensorEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); + +/** + * Get the data rate (number of events per second) of a gamepad sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns the data rate, or 0.0f if the data rate is not available. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); + +/** + * Get the current state of a gamepad sensor. + * + * The number of values and interpretation of the data is sensor dependent. + * See SDL_sensor.h for the details for each type of sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \param data a pointer filled with the current sensor state. + * \param num_values the number of values to write to data. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); + +/** + * Start a rumble effect on a gamepad. + * + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param gamepad the gamepad to vibrate. + * \param low_frequency_rumble the intensity of the low frequency (left) + * rumble motor, from 0 to 0xFFFF. + * \param high_frequency_rumble the intensity of the high frequency (right) + * rumble motor, from 0 to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); + +/** + * Start a rumble effect in the gamepad's triggers. + * + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. + * + * Note that this is rumbling of the _triggers_ and not the gamepad as a + * whole. This is currently only supported on Xbox One gamepads. If you want + * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param gamepad the gamepad to vibrate. + * \param left_rumble the intensity of the left trigger rumble motor, from 0 + * to 0xFFFF. + * \param right_rumble the intensity of the right trigger rumble motor, from 0 + * to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RumbleGamepad + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); + +/** + * Update a gamepad's LED color. + * + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. + * + * For gamepads with a single color LED, the maximum of the RGB values will be + * used as the LED brightness. + * + * \param gamepad the gamepad to update. + * \param red the intensity of the red LED. + * \param green the intensity of the green LED. + * \param blue the intensity of the blue LED. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); + +/** + * Send a gamepad specific effect packet. + * + * \param gamepad the gamepad to affect. + * \param data the data to send to the gamepad. + * \param size the size of the data to send to the gamepad. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); + +/** + * Close a gamepad previously opened with SDL_OpenGamepad(). + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenGamepad + */ +extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); + +/** + * Return the sfSymbolsName for a given button on a gamepad on Apple + * platforms. + * + * \param gamepad the gamepad to query. + * \param button a button on the gamepad. + * \returns the sfSymbolsName or NULL if the name can't be found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); + +/** + * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms. + * + * \param gamepad the gamepad to query. + * \param axis an axis on the gamepad. + * \returns the sfSymbolsName or NULL if the name can't be found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAppleSFSymbolsNameForButton + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_gamepad_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gpu.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gpu.h new file mode 100644 index 0000000000..b616619099 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_gpu.h @@ -0,0 +1,4213 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: GPU */ + +/** + * # CategoryGPU + * + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next, the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other rendering data: use + * SDL_CreateGPUBuffer() and SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_CreateGPUTexture() and + * SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. It also has a CLI + * interface for offline precompilation as well. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. + */ + +#ifndef SDL_gpu_h_ +#define SDL_gpu_h_ + +#include +#include +#include +#include +#include +#include + +#include +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* Type Declarations */ + +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ +typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ +typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ +typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ +typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ +typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ +typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ +typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ +typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ +typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ +typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ +typedef struct SDL_GPUFence SDL_GPUFence; + +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUPrimitiveType +{ + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ +} SDL_GPUPrimitiveType; + +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef enum SDL_GPULoadOp +{ + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ +} SDL_GPULoadOp; + +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef enum SDL_GPUStoreOp +{ + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ +} SDL_GPUStoreOp; + +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUIndexElementSize +{ + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ +} SDL_GPUIndexElementSize; + +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE + * + * For SAMPLER usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM + * + * For COLOR_TARGET usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * + * For STORAGE usages, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT + * + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat + */ +typedef enum SDL_GPUTextureFormat +{ + SDL_GPU_TEXTUREFORMAT_INVALID, + + /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, + SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, + SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, + SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + /* Compressed Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, + /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, + /* Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, + /* Unsigned Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_UINT, + SDL_GPU_TEXTUREFORMAT_R8G8_UINT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT, + SDL_GPU_TEXTUREFORMAT_R16_UINT, + SDL_GPU_TEXTUREFORMAT_R16G16_UINT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, + /* SRGB Unsigned Normalized Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, + /* Compressed SRGB Unsigned Normalized Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, + /* Depth Formats */ + SDL_GPU_TEXTUREFORMAT_D16_UNORM, + SDL_GPU_TEXTUREFORMAT_D24_UNORM, + SDL_GPU_TEXTUREFORMAT_D32_FLOAT, + SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT +} SDL_GPUTextureFormat; + +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ +typedef Uint32 SDL_GPUTextureUsageFlags; + +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ +typedef enum SDL_GPUTextureType +{ + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ +} SDL_GPUTextureType; + +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ +typedef enum SDL_GPUSampleCount +{ + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ +} SDL_GPUSampleCount; + + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GPUCubeMapFace +{ + SDL_GPU_CUBEMAPFACE_POSITIVEX, + SDL_GPU_CUBEMAPFACE_NEGATIVEX, + SDL_GPU_CUBEMAPFACE_POSITIVEY, + SDL_GPU_CUBEMAPFACE_NEGATIVEY, + SDL_GPU_CUBEMAPFACE_POSITIVEZ, + SDL_GPU_CUBEMAPFACE_NEGATIVEZ +} SDL_GPUCubeMapFace; + +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * If you use a STORAGE flag, the data in the buffer must respect std140 + * layout conventions. In practical terms this means you must ensure that vec3 + * and vec4 fields are 16-byte aligned. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ +typedef Uint32 SDL_GPUBufferUsageFlags; + +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ +typedef enum SDL_GPUTransferBufferUsage +{ + SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, + SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD +} SDL_GPUTransferBufferUsage; + +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +typedef enum SDL_GPUShaderStage +{ + SDL_GPU_SHADERSTAGE_VERTEX, + SDL_GPU_SHADERSTAGE_FRAGMENT +} SDL_GPUShaderStage; + +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +typedef Uint32 SDL_GPUShaderFormat; + +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUVertexElementFormat +{ + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + + /* 32-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_INT, + SDL_GPU_VERTEXELEMENTFORMAT_INT2, + SDL_GPU_VERTEXELEMENTFORMAT_INT3, + SDL_GPU_VERTEXELEMENTFORMAT_INT4, + + /* 32-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_UINT, + SDL_GPU_VERTEXELEMENTFORMAT_UINT2, + SDL_GPU_VERTEXELEMENTFORMAT_UINT3, + SDL_GPU_VERTEXELEMENTFORMAT_UINT4, + + /* 32-bit Floats */ + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4, + + /* 8-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2, + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4, + + /* 8-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2, + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4, + + /* 8-bit Signed Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4_NORM, + + /* 8-bit Unsigned Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM, + + /* 16-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2, + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4, + + /* 16-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2, + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4, + + /* 16-bit Signed Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4_NORM, + + /* 16-bit Unsigned Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4_NORM, + + /* 16-bit Floats */ + SDL_GPU_VERTEXELEMENTFORMAT_HALF2, + SDL_GPU_VERTEXELEMENTFORMAT_HALF4 +} SDL_GPUVertexElementFormat; + +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUVertexInputRate +{ + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ +} SDL_GPUVertexInputRate; + +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUFillMode +{ + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ +} SDL_GPUFillMode; + +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUCullMode +{ + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ +} SDL_GPUCullMode; + +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUFrontFace +{ + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ +} SDL_GPUFrontFace; + +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUCompareOp +{ + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ +} SDL_GPUCompareOp; + +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUStencilOp +{ + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ +} SDL_GPUStencilOp; + +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUBlendOp +{ + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ +} SDL_GPUBlendOp; + +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUBlendFactor +{ + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ +} SDL_GPUBlendFactor; + +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef Uint8 SDL_GPUColorComponentFlags; + +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUFilter +{ + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ +} SDL_GPUFilter; + +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUSamplerMipmapMode +{ + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ +} SDL_GPUSamplerMipmapMode; + +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUSamplerAddressMode +{ + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ +} SDL_GPUSamplerAddressMode; + +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + */ +typedef enum SDL_GPUPresentMode +{ + SDL_GPU_PRESENTMODE_VSYNC, + SDL_GPU_PRESENTMODE_IMMEDIATE, + SDL_GPU_PRESENTMODE_MAILBOX +} SDL_GPUPresentMode; + +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + */ +typedef enum SDL_GPUSwapchainComposition +{ + SDL_GPU_SWAPCHAINCOMPOSITION_SDR, + SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, + SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 +} SDL_GPUSwapchainComposition; + +/* Structures */ + +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ +typedef struct SDL_GPUViewport +{ + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ +} SDL_GPUViewport; + +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ +typedef struct SDL_GPUTextureTransferInfo +{ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ +} SDL_GPUTextureTransferInfo; + +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ +typedef struct SDL_GPUTransferBufferLocation +{ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ +} SDL_GPUTransferBufferLocation; + +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ +typedef struct SDL_GPUTextureLocation +{ + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ +} SDL_GPUTextureLocation; + +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CreateGPUTexture + */ +typedef struct SDL_GPUTextureRegion +{ + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ +} SDL_GPUTextureRegion; + +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitRegion +{ + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ +} SDL_GPUBlitRegion; + +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ +typedef struct SDL_GPUBufferLocation +{ + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ +} SDL_GPUBufferLocation; + +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ +typedef struct SDL_GPUBufferRegion +{ + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ +} SDL_GPUBufferRegion; + +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect + */ +typedef struct SDL_GPUIndirectDrawCommand +{ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ +} SDL_GPUIndirectDrawCommand; + +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ +typedef struct SDL_GPUIndexedIndirectDrawCommand +{ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ +} SDL_GPUIndexedIndirectDrawCommand; + +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ +typedef struct SDL_GPUIndirectDispatchCommand +{ + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ +} SDL_GPUIndirectDispatchCommand; + +/* State structures */ + +/** + * A structure specifying the parameters of a sampler. + * + * Note that mip_lod_bias is a no-op for the Metal driver. For Metal, LOD bias + * must be applied via shader instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_GPUFilter + * \sa SDL_GPUSamplerMipmapMode + * \sa SDL_GPUSamplerAddressMode + * \sa SDL_GPUCompareOp + */ +typedef struct SDL_GPUSamplerCreateInfo +{ + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUSamplerCreateInfo; + +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputRate + */ +typedef struct SDL_GPUVertexBufferDescription +{ + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< Reserved for future use. Must be set to 0. */ +} SDL_GPUVertexBufferDescription; + +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUVertexElementFormat + */ +typedef struct SDL_GPUVertexAttribute +{ + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ +} SDL_GPUVertexAttribute; + +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ +typedef struct SDL_GPUVertexInputState +{ + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ +} SDL_GPUVertexInputState; + +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ +typedef struct SDL_GPUStencilOpState +{ + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ +} SDL_GPUStencilOpState; + +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState +{ + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +typedef struct SDL_GPUShaderCreateInfo +{ + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUShaderCreateInfo; + +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ +typedef struct SDL_GPUTextureCreateInfo +{ + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUTextureCreateInfo; + +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ +typedef struct SDL_GPUBufferCreateInfo +{ + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUBufferCreateInfo; + +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ +typedef struct SDL_GPUTransferBufferCreateInfo +{ + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUTransferBufferCreateInfo; + +/* Pipeline state structures */ + +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * Note that SDL_GPU_FILLMODE_LINE is not supported on many Android devices. + * For those devices, the fill mode will automatically fall back to FILL. + * + * Also note that the D3D12 driver will enable depth clamping even if + * enable_depth_clip is true. If you need this clamp+clip behavior, consider + * enabling depth clip and then manually clamping depth in your fragment + * shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPURasterizerState +{ + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPURasterizerState; + +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUMultisampleState +{ + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Reserved for future use. Must be set to 0. */ + bool enable_mask; /**< Reserved for future use. Must be set to false. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUMultisampleState; + +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUDepthStencilState +{ + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUDepthStencilState; + +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription +{ + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; + +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUColorTargetDescription + * \sa SDL_GPUTextureFormat + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo +{ + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; + +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUShader + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUGraphicsPipelineCreateInfo +{ + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUGraphicsPipelineCreateInfo; + +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_GPUShaderFormat + */ +typedef struct SDL_GPUComputePipelineCreateInfo +{ + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUComputePipelineCreateInfo; + +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo +{ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; + +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo +{ + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; + +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; + +/* Binding structs */ + +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ +typedef struct SDL_GPUBufferBinding +{ + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ +} SDL_GPUBufferBinding; + +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ +typedef struct SDL_GPUTextureSamplerBinding +{ + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ +} SDL_GPUTextureSamplerBinding; + +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding +{ + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; + +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding +{ + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; + +/* Functions */ + +/* Device */ + +/** + * Checks for GPU runtime support. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats + */ +extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice( + SDL_GPUShaderFormat format_flags, + bool debug_mode, + const char *name); + +/** + * Creates a GPU context. + * + * These are the supported properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. + * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to + * use, if a specific one is desired. + * + * These are the current shader format properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to + * provide shaders for an NDA platform. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to + * provide SPIR-V shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to + * provide DXIL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to + * provide Metal shader libraries if applicable. + * + * With the D3D12 renderer: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to + * use for all vertex semantics, default is "TEXCOORD". + * + * \param props the properties to use. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties + */ +extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties( + SDL_PropertiesID props); + +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" + +/** + * Destroys a GPU context previously returned by SDL_CreateGPUDevice. + * + * \param device a GPU Context to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); + +/** + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. + * + * \param device a GPU context to query. + * \returns the name of the device's driver, or NULL on error. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); + +/* State Creation */ + +/** + * Creates a pipeline object to be used in a compute workflow. + * + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. + * + * For SPIR-V shaders, use the following resource sets: + * + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ +extern SDL_DECLSPEC SDL_GPUComputePipeline * SDLCALL SDL_CreateGPUComputePipeline( + SDL_GPUDevice *device, + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" + +/** + * Creates a pipeline object to be used in a graphics workflow. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ +extern SDL_DECLSPEC SDL_GPUGraphicsPipeline * SDLCALL SDL_CreateGPUGraphicsPipeline( + SDL_GPUDevice *device, + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" + +/** + * Creates a sampler object to be used when binding textures in a graphics + * workflow. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ +extern SDL_DECLSPEC SDL_GPUSampler * SDLCALL SDL_CreateGPUSampler( + SDL_GPUDevice *device, + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" + +/** + * Creates a shader to be used when creating a graphics pipeline. + * + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. + * + * For SPIR-V shaders, use the following resource sets: + * + * For vertex shaders: + * + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers + * + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ +extern SDL_DECLSPEC SDL_GPUShader * SDLCALL SDL_CreateGPUShader( + SDL_GPUDevice *device, + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" + +/** + * Creates a texture object to be used in graphics or compute workflows. + * + * The contents of this texture are undefined until data is written to the + * texture. + * + * Note that certain combinations of usage flags are invalid. For example, a + * texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags. + * + * If you request a sample count higher than the hardware supports, the + * 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_GPU_TEXTURE_CREATE_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_TEXTURE_CREATE_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_TEXTURE_CREATE_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_TEXTURE_CREATE_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_TEXTURE_CREATE_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_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this Uint8 value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \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 + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + * \sa SDL_GPUTextureSupportsFormat + */ +extern SDL_DECLSPEC SDL_GPUTexture * SDLCALL SDL_CreateGPUTexture( + SDL_GPUDevice *device, + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" + +/** + * Creates a buffer object to be used in graphics or compute workflows. + * + * The contents of this buffer are undefined until data is written to the + * buffer. + * + * Note that certain combinations of usage flags are invalid. For example, a + * buffer cannot have both the VERTEX and INDEX flags. + * + * If you use a STORAGE flag, the data in the buffer must respect std140 + * layout conventions. In practical terms this means you must ensure that vec3 + * and vec4 fields are 16-byte aligned. + * + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ +extern SDL_DECLSPEC SDL_GPUBuffer * SDLCALL SDL_CreateGPUBuffer( + SDL_GPUDevice *device, + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" + +/** + * Creates a transfer buffer to be used when uploading to or downloading from + * graphics resources. + * + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ +extern SDL_DECLSPEC SDL_GPUTransferBuffer * SDLCALL SDL_CreateGPUTransferBuffer( + SDL_GPUDevice *device, + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" + +/* Debug Naming */ + +/** + * Sets an arbitrary string constant to label a buffer. + * + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. + * + * \param device a GPU Context. + * \param buffer a buffer to attach the name to. + * \param text a UTF-8 string constant to mark as the name of the buffer. + * + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( + SDL_GPUDevice *device, + SDL_GPUBuffer *buffer, + const char *text); + +/** + * Sets an arbitrary string constant to label a texture. + * + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. + * + * \param device a GPU Context. + * \param texture a texture to attach the name to. + * \param text a UTF-8 string constant to mark as the name of the texture. + * + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( + SDL_GPUDevice *device, + SDL_GPUTexture *texture, + const char *text); + +/** + * Inserts an arbitrary string label into the command buffer callstream. + * + * Useful for debugging. + * + * \param command_buffer a command buffer. + * \param text a UTF-8 string constant to insert as the label. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( + SDL_GPUCommandBuffer *command_buffer, + const char *text); + +/** + * Begins a debug group with an arbitary name. + * + * Used for denoting groups of calls when viewing the command buffer + * callstream in a graphics debugging tool. + * + * Each call to SDL_PushGPUDebugGroup must have a corresponding call to + * SDL_PopGPUDebugGroup. + * + * On some backends (e.g. Metal), pushing a debug group during a + * render/blit/compute pass will create a group that is scoped to the native + * pass rather than the command buffer. For best results, if you push a debug + * group during a pass, always pop it in the same pass. + * + * \param command_buffer a command buffer. + * \param name a UTF-8 string constant that names the group. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PopGPUDebugGroup + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( + SDL_GPUCommandBuffer *command_buffer, + const char *name); + +/** + * Ends the most-recently pushed debug group. + * + * \param command_buffer a command buffer. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PushGPUDebugGroup + */ +extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( + SDL_GPUCommandBuffer *command_buffer); + +/* Disposal */ + +/** + * Frees the given texture as soon as it is safe to do so. + * + * You must not reference the texture after calling this function. + * + * \param device a GPU context. + * \param texture a texture to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( + SDL_GPUDevice *device, + SDL_GPUTexture *texture); + +/** + * Frees the given sampler as soon as it is safe to do so. + * + * You must not reference the sampler after calling this function. + * + * \param device a GPU context. + * \param sampler a sampler to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( + SDL_GPUDevice *device, + SDL_GPUSampler *sampler); + +/** + * Frees the given buffer as soon as it is safe to do so. + * + * You must not reference the buffer after calling this function. + * + * \param device a GPU context. + * \param buffer a buffer to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( + SDL_GPUDevice *device, + SDL_GPUBuffer *buffer); + +/** + * Frees the given transfer buffer as soon as it is safe to do so. + * + * You must not reference the transfer buffer after calling this function. + * + * \param device a GPU context. + * \param transfer_buffer a transfer buffer to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer); + +/** + * Frees the given compute pipeline as soon as it is safe to do so. + * + * You must not reference the compute pipeline after calling this function. + * + * \param device a GPU context. + * \param compute_pipeline a compute pipeline to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( + SDL_GPUDevice *device, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Frees the given shader as soon as it is safe to do so. + * + * You must not reference the shader after calling this function. + * + * \param device a GPU context. + * \param shader a shader to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( + SDL_GPUDevice *device, + SDL_GPUShader *shader); + +/** + * Frees the given graphics pipeline as soon as it is safe to do so. + * + * You must not reference the graphics pipeline after calling this function. + * + * \param device a GPU context. + * \param graphics_pipeline a graphics pipeline to be destroyed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( + SDL_GPUDevice *device, + SDL_GPUGraphicsPipeline *graphics_pipeline); + +/** + * Acquire a command buffer. + * + * This command buffer is managed by the implementation and should not be + * freed by the user. The command buffer may only be used on the thread it was + * acquired on. The command buffer should be submitted on the thread it was + * acquired on. + * + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. + * + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC SDL_GPUCommandBuffer * SDLCALL SDL_AcquireGPUCommandBuffer( + SDL_GPUDevice *device); + +/* Uniform Data */ + +/** + * Pushes data to a vertex uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * The data being pushed must respect std140 layout conventions. In practical + * terms this means you must ensure that vec3 and vec4 fields are 16-byte + * aligned. + * + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. + * \param data client data to write. + * \param length the length of the data to write. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/** + * Pushes data to a fragment uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * The data being pushed must respect std140 layout conventions. In practical + * terms this means you must ensure that vec3 and vec4 fields are 16-byte + * aligned. + * + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. + * \param data client data to write. + * \param length the length of the data to write. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/** + * Pushes data to a uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * The data being pushed must respect std140 layout conventions. In practical + * terms this means you must ensure that vec3 and vec4 fields are 16-byte + * aligned. + * + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. + * \param data client data to write. + * \param length the length of the data to write. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/* Graphics State */ + +/** + * Begins a render pass on a command buffer. + * + * A render pass consists of a set of texture subresources (or depth slices in + * the 3D texture case) which will be rendered to during the render pass, + * along with corresponding clear values and load/store operations. All + * operations related to graphics pipelines must take place inside of a render + * pass. A default viewport and scissor state are automatically set when this + * is called. You cannot begin another render pass, or begin a compute pass or + * copy pass until you have ended the render pass. + * + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. + * \returns a render pass handle. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EndGPURenderPass + */ +extern SDL_DECLSPEC SDL_GPURenderPass * SDLCALL SDL_BeginGPURenderPass( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); + +/** + * Binds a graphics pipeline on a render pass to be used in rendering. + * + * A graphics pipeline must be bound before making any draw calls. + * + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); + +/** + * Sets the current viewport state on a command buffer. + * + * \param render_pass a render pass handle. + * \param viewport the viewport to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); + +/** + * Sets the current scissor state on a command buffer. + * + * \param render_pass a render pass handle. + * \param scissor the scissor area to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); + +/** + * Binds vertex buffers on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); + +/** + * Binds an index buffer on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); + +/** + * Binds texture-sampler pairs for use on the vertex shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures for use on the vertex shader. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers for use on the vertex shader. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/** + * Binds texture-sampler pairs for use on the fragment shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures for use on the fragment shader. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers for use on the fragment shader. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/* Drawing */ + +/** + * Draws data using bound graphics state with an index buffer and instancing + * enabled. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); + +/** + * Draws data using bound graphics state. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); + +/** + * Draws data using bound graphics state and with draw parameters set from a + * buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( + SDL_GPURenderPass *render_pass, + SDL_GPUBuffer *buffer, + Uint32 offset, + Uint32 draw_count); + +/** + * Draws data using bound graphics state with an index buffer enabled and with + * draw parameters set from a buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( + SDL_GPURenderPass *render_pass, + SDL_GPUBuffer *buffer, + Uint32 offset, + Uint32 draw_count); + +/** + * Ends the given render pass. + * + * All bound graphics state on the render pass command buffer is unset. The + * render pass handle is now invalid. + * + * \param render_pass a render pass handle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( + SDL_GPURenderPass *render_pass); + +/* Compute Pass */ + +/** + * Begins a compute pass on a command buffer. + * + * A compute pass is defined by a set of texture subresources and buffers that + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. + * + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! + * + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. + * \returns a compute pass handle. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EndGPUComputePass + */ +extern SDL_DECLSPEC SDL_GPUComputePass * SDLCALL SDL_BeginGPUComputePass( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); + +/** + * Binds a compute pipeline on a command buffer for use in compute dispatch. + * + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures as readonly for use on the compute pipeline. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers as readonly for use on the compute pipeline. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. + * + * Be sure your shader is set up according to the requirements documented in + * SDL_CreateGPUShader(). + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/** + * Dispatches compute work. + * + * You must not call this function before binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); + +/** + * Dispatches compute work with parameters set from a buffer. + * + * The buffer layout should match the layout of + * SDL_GPUIndirectDispatchCommand. You must not call this function before + * binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param buffer a buffer containing dispatch parameters. + * \param offset the offset to start reading from the dispatch buffer. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( + SDL_GPUComputePass *compute_pass, + SDL_GPUBuffer *buffer, + Uint32 offset); + +/** + * Ends the current compute pass. + * + * All bound compute state on the command buffer is unset. The compute pass + * handle is now invalid. + * + * \param compute_pass a compute pass handle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( + SDL_GPUComputePass *compute_pass); + +/* TransferBuffer Data */ + +/** + * Maps a transfer buffer into application address space. + * + * You must unmap the transfer buffer before encoding upload commands. The + * memory is owned by the graphics driver - do NOT call SDL_free() on the + * returned pointer. + * + * \param device a GPU context. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void * SDLCALL SDL_MapGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); + +/** + * Unmaps a previously mapped transfer buffer. + * + * \param device a GPU context. + * \param transfer_buffer a previously mapped transfer buffer. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer); + +/* Copy Pass */ + +/** + * Begins a copy pass on a command buffer. + * + * All operations related to copying to or from buffers or textures take place + * inside a copy pass. You must not begin another copy pass, or a render pass + * or compute pass before ending the copy pass. + * + * \param command_buffer a command buffer. + * \returns a copy pass handle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUCopyPass * SDLCALL SDL_BeginGPUCopyPass( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Uploads data from a transfer buffer to a texture. + * + * The upload occurs on the GPU timeline. You may assume that the upload has + * finished in subsequent commands. + * + * You must align the data in the transfer buffer to a multiple of the texel + * size of the texture format. + * + * \param copy_pass a copy pass handle. + * \param source the source transfer buffer with image layout information. + * \param destination the destination texture region. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); + +/** + * Uploads data from a transfer buffer to a buffer. + * + * The upload occurs on the GPU timeline. You may assume that the upload has + * finished in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source the source transfer buffer with offset. + * \param destination the destination buffer with offset and size. + * \param cycle if true, cycles the buffer if it is already bound, otherwise + * overwrites the data. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); + +/** + * Performs a texture-to-texture copy. + * + * This copy occurs on the GPU timeline. You may assume the copy has finished + * in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source a source texture region. + * \param destination a destination texture region. + * \param w the width of the region to copy. + * \param h the height of the region to copy. + * \param d the depth of the region to copy. + * \param cycle if true, cycles the destination texture if the destination + * texture is bound, otherwise overwrites the data. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, + Uint32 w, + Uint32 h, + Uint32 d, + bool cycle); + +/** + * Performs a buffer-to-buffer copy. + * + * This copy occurs on the GPU timeline. You may assume the copy has finished + * in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source the buffer and offset to copy from. + * \param destination the buffer and offset to copy to. + * \param size the length of the buffer to copy. + * \param cycle if true, cycles the destination buffer if it is already bound, + * otherwise overwrites the data. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, + Uint32 size, + bool cycle); + +/** + * Copies data from a texture to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source texture region. + * \param destination the destination transfer buffer with image layout + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); + +/** + * Copies data from a buffer to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source buffer with offset and size. + * \param destination the destination transfer buffer with offset. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); + +/** + * Ends the current copy pass. + * + * \param copy_pass a copy pass handle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( + SDL_GPUCopyPass *copy_pass); + +/** + * Generates mipmaps for the given texture. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command_buffer. + * \param texture a texture with more than 1 mip level. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_GPUTexture *texture); + +/** + * Blits from a source texture region to a destination texture region. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); + +/* Submission/Presentation */ + +/** + * Determines whether a swapchain composition is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUSwapchainComposition swapchain_composition); + +/** + * Determines whether a presentation mode is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUPresentMode present_mode); + +/** + * Claims a window, creating a swapchain structure for it. + * + * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created + * the window. + * + * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and + * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_ReleaseWindowFromGPUDevice + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Unclaims a window, destroying its swapchain structure. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Changes the swapchain parameters for the given claimed window. + * + * This function will fail if the requested present mode or swapchain + * composition are unsupported by the device. Check if the parameters are + * supported via SDL_WindowSupportsGPUPresentMode / + * SDL_WindowSupportsGPUSwapchainComposition prior to calling this function. + * + * SDL_GPU_PRESENTMODE_VSYNC with SDL_GPU_SWAPCHAINCOMPOSITION_SDR are always + * supported. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); + +/** + * Obtains the texture format of the swapchain for the given window. + * + * Note that this format can change if the swapchain parameters change. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * \returns the texture format of the swapchain. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Acquire a texture to use in presentation. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. + * + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * The swapchain texture is write-only and cannot be used as a sampler or for + * another reading operation. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Submits a command buffer so its commands can be processed on the GPU. + * + * It is invalid to use the command buffer after this is called. + * + * This must be called from the thread the command buffer was acquired on. + * + * All commands in the submission are guaranteed to begin executing before any + * command in a subsequent submission begins executing. + * + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Submits a command buffer so its commands can be processed on the GPU, and + * acquires a fence associated with the command buffer. + * + * You must release this fence when it is no longer needed or it will cause a + * leak. It is invalid to use the command buffer after this is called. + * + * This must be called from the thread the command buffer was acquired on. + * + * All commands in the submission are guaranteed to begin executing before any + * command in a subsequent submission begins executing. + * + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_ReleaseGPUFence + */ +extern SDL_DECLSPEC SDL_GPUFence * SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Blocks the thread until the GPU is completely idle. + * + * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitForGPUFences + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( + SDL_GPUDevice *device); + +/** + * Blocks the thread until the given fences are signaled. + * + * \param device a GPU context. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_WaitForGPUIdle + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( + SDL_GPUDevice *device, + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); + +/** + * Checks the status of a fence. + * + * \param device a GPU context. + * \param fence a fence. + * \returns true if the fence is signaled, false if it is not. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( + SDL_GPUDevice *device, + SDL_GPUFence *fence); + +/** + * Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence. + * + * You must not reference the fence after calling this function. + * + * \param device a GPU context. + * \param fence a fence. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( + SDL_GPUDevice *device, + SDL_GPUFence *fence); + +/* Format Info */ + +/** + * Obtains the texel block size for a texture format. + * + * \param format the texture format you want to know the texel size of. + * \returns the texel block size of the texture format. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( + SDL_GPUTextureFormat format); + +/** + * Determines whether a texture format is supported for a given type and + * usage. + * + * \param device a GPU context. + * \param format the texture format to check. + * \param type the type of texture (2D, 3D, Cube). + * \param usage a bitmask of all usage scenarios to check. + * \returns whether the texture format is supported for this type and usage. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( + SDL_GPUDevice *device, + SDL_GPUTextureFormat format, + SDL_GPUTextureType type, + SDL_GPUTextureUsageFlags usage); + +/** + * Determines if a sample count for a texture format is supported. + * + * \param device a GPU context. + * \param format the texture format to check. + * \param sample_count the sample count to check. + * \returns whether the sample count is supported for this texture format. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( + SDL_GPUDevice *device, + SDL_GPUTextureFormat format, + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); + +#ifdef SDL_PLATFORM_GDK + +/** + * Call this to suspend GPU operation on Xbox when you receive the + * SDL_EVENT_DID_ENTER_BACKGROUND event. + * + * Do NOT call any SDL_GPU functions after calling this function! This must + * also be called before calling SDL_GDKSuspendComplete. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + */ +extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); + +/** + * Call this to resume GPU operation on Xbox when you receive the + * SDL_EVENT_WILL_ENTER_FOREGROUND event. + * + * When resuming, this function MUST be called before calling any other + * SDL_GPU functions. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + */ +extern SDL_DECLSPEC void SDLCALL SDL_GDKResumeGPU(SDL_GPUDevice *device); + +#endif /* SDL_PLATFORM_GDK */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#include + +#endif /* SDL_gpu_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_guid.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_guid.h similarity index 70% rename from code/thirdparty/SDL2-2.32.8/include/SDL_guid.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_guid.h index fd9a50e322..312c42c031 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_guid.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_guid.h @@ -26,30 +26,27 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ -#include "SDL_stdinc.h" -#include "SDL_error.h" +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif /** - * An SDL_GUID is a 128-bit identifier. - * - * This is an acronym for "Globally Unique ID." + * An SDL_GUID is a 128-bit identifier for an input device that identifies + * that device across runs of SDL programs on the same platform. * - * While a GUID can be used to assign a unique value to almost anything, in - * SDL these are largely used to identify input devices across runs of SDL - * programs on the same platform.If the device is detached and then - * re-attached to a different port, or if the base system is rebooted, the - * device should still report the same GUID. + * If the device is detached and then re-attached to a different port, or if + * the base system is rebooted, the device should still report the same GUID. * * GUIDs are as precise as possible but are not guaranteed to distinguish * physically distinct but equivalent devices. For example, two game @@ -58,6 +55,8 @@ extern "C" { * * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -68,17 +67,17 @@ typedef struct SDL_GUID { /** * Get an ASCII string representation for a given SDL_GUID. * - * You should supply at least 33 bytes for pszGUID. - * * \param guid the SDL_GUID you wish to convert to string. * \param pszGUID buffer in which to write the ASCII string. - * \param cbGUID the size of pszGUID. + * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 2.24.0. + * \threadsafety It is safe to call this function from any thread. * - * \sa SDL_GUIDFromString + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StringToGUID */ -extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID); +extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID); /** * Convert a GUID string into a SDL_GUID structure. @@ -90,18 +89,18 @@ extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 2.24.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ -extern DECLSPEC SDL_GUID SDLCALL SDL_GUIDFromString(const char *pchGUID); +extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_StringToGUID(const char *pchGUID); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_guid_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_haptic.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_haptic.h similarity index 67% rename from code/thirdparty/SDL2-2.32.8/include/SDL_haptic.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_haptic.h index f679c5734e..a45335b285 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_haptic.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_haptic.h @@ -22,63 +22,68 @@ /** * # CategoryHaptic * - * SDL haptic subsystem allows you to control haptic (force feedback) devices. + * The SDL haptic subsystem manages haptic (force feedback) devices. * * The basic usage is as follows: * * - Initialize the subsystem (SDL_INIT_HAPTIC). * - Open a haptic device. - * - SDL_HapticOpen() to open from index. - * - SDL_HapticOpenFromJoystick() to open from an existing joystick. + * - SDL_OpenHaptic() to open from index. + * - SDL_OpenHapticFromJoystick() to open from an existing joystick. * - Create an effect (SDL_HapticEffect). - * - Upload the effect with SDL_HapticNewEffect(). - * - Run the effect with SDL_HapticRunEffect(). - * - (optional) Free the effect with SDL_HapticDestroyEffect(). - * - Close the haptic device with SDL_HapticClose(). + * - Upload the effect with SDL_CreateHapticEffect(). + * - Run the effect with SDL_RunHapticEffect(). + * - (optional) Free the effect with SDL_DestroyHapticEffect(). + * - Close the haptic device with SDL_CloseHaptic(). * * Simple rumble example: * * ```c - * SDL_Haptic *haptic; + * SDL_Haptic *haptic = NULL; * * // Open the device - * haptic = SDL_HapticOpen( 0 ); + * SDL_HapticID *haptics = SDL_GetHaptics(NULL); + * if (haptics) { + * haptic = SDL_OpenHaptic(haptics[0]); + * SDL_free(haptics); + * } * if (haptic == NULL) - * return -1; + * return; * * // Initialize simple rumble - * if (SDL_HapticRumbleInit( haptic ) != 0) - * return -1; + * if (!SDL_InitHapticRumble(haptic)) + * return; * * // Play effect at 50% strength for 2 seconds - * if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0) - * return -1; - * SDL_Delay( 2000 ); + * if (!SDL_PlayHapticRumble(haptic, 0.5, 2000)) + * return; + * SDL_Delay(2000); * * // Clean up - * SDL_HapticClose( haptic ); + * SDL_CloseHaptic(haptic); * ``` * * Complete example: * * ```c - * int test_haptic( SDL_Joystick * joystick ) { + * bool test_haptic(SDL_Joystick *joystick) + * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; * int effect_id; * * // Open the device - * haptic = SDL_HapticOpenFromJoystick( joystick ); - * if (haptic == NULL) return -1; // Most likely joystick isn't haptic + * haptic = SDL_OpenHapticFromJoystick(joystick); + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves - * if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) { - * SDL_HapticClose(haptic); // No sine effect - * return -1; + * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { + * SDL_CloseHaptic(haptic); // No sine effect + * return false; * } * * // Create the effect - * SDL_memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default + * SDL_memset(&effect, 0, sizeof(SDL_HapticEffect)); // 0 is safe default * effect.type = SDL_HAPTIC_SINE; * effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates * effect.periodic.direction.dir[0] = 18000; // Force comes from south @@ -89,37 +94,40 @@ * effect.periodic.fade_length = 1000; // Takes 1 second to fade away * * // Upload the effect - * effect_id = SDL_HapticNewEffect( haptic, &effect ); + * effect_id = SDL_CreateHapticEffect(haptic, &effect); * * // Test the effect - * SDL_HapticRunEffect( haptic, effect_id, 1 ); - * SDL_Delay( 5000); // Wait for the effect to finish + * SDL_RunHapticEffect(haptic, effect_id, 1); + * SDL_Delay(5000); // Wait for the effect to finish * * // We destroy the effect, although closing the device also does this - * SDL_HapticDestroyEffect( haptic, effect_id ); + * SDL_DestroyHapticEffect(haptic, effect_id); * * // Close the device - * SDL_HapticClose(haptic); + * SDL_CloseHaptic(haptic); * - * return 0; // Success + * return true; // Success * } * ``` + * + * Note that the SDL haptic subsystem is not thread-safe. */ + #ifndef SDL_haptic_h_ #define SDL_haptic_h_ -#include "SDL_stdinc.h" -#include "SDL_error.h" -#include "SDL_joystick.h" +#include +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ -/* FIXME: For SDL 2.1, adjust all the magnitude variables to be Uint16 (0xFFFF). +/* FIXME: * * At the moment the magnitude variables are mixed between signed/unsigned, and * it is also not made clear that ALL of those variables expect a max of 0x7FFF. @@ -131,16 +139,15 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * \brief The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_HapticOpen - * \sa SDL_HapticOpenFromJoystick - * \sa SDL_HapticClose + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct _SDL_Haptic; -typedef struct _SDL_Haptic SDL_Haptic; +typedef struct SDL_Haptic SDL_Haptic; /** @@ -160,54 +167,63 @@ typedef struct _SDL_Haptic SDL_Haptic; * * Constant haptic effect. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticCondition */ -#define SDL_HAPTIC_CONSTANT (1u<<0) +#define SDL_HAPTIC_CONSTANT (1u<<0) /** * Sine wave effect supported. * * Periodic haptic effect that simulates sine waves. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticPeriodic */ -#define SDL_HAPTIC_SINE (1u<<1) +#define SDL_HAPTIC_SINE (1u<<1) /** - * Left/Right effect supported. + * Square wave effect supported. * - * Haptic effect for direct control over high/low frequency motors. + * Periodic haptic effect that simulates square waves. * - * \sa SDL_HapticLeftRight + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic */ -#define SDL_HAPTIC_LEFTRIGHT (1u<<2) - -/* !!! FIXME: put this back when we have more bits in 2.1 */ -/* #define SDL_HAPTIC_SQUARE (1<<2) */ +#define SDL_HAPTIC_SQUARE (1u<<2) /** * Triangle wave effect supported. * * Periodic haptic effect that simulates triangular waves. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticPeriodic */ -#define SDL_HAPTIC_TRIANGLE (1u<<3) +#define SDL_HAPTIC_TRIANGLE (1u<<3) /** * Sawtoothup wave effect supported. * * Periodic haptic effect that simulates saw tooth up waves. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticPeriodic */ -#define SDL_HAPTIC_SAWTOOTHUP (1u<<4) +#define SDL_HAPTIC_SAWTOOTHUP (1u<<4) /** * Sawtoothdown wave effect supported. * * Periodic haptic effect that simulates saw tooth down waves. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5) @@ -217,9 +233,11 @@ typedef struct _SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticRamp */ -#define SDL_HAPTIC_RAMP (1u<<6) +#define SDL_HAPTIC_RAMP (1u<<6) /** * Spring effect supported - uses axes position. @@ -227,9 +245,11 @@ typedef struct _SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticCondition */ -#define SDL_HAPTIC_SPRING (1u<<7) +#define SDL_HAPTIC_SPRING (1u<<7) /** * Damper effect supported - uses axes velocity. @@ -237,9 +257,11 @@ typedef struct _SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticCondition */ -#define SDL_HAPTIC_DAMPER (1u<<8) +#define SDL_HAPTIC_DAMPER (1u<<8) /** * Inertia effect supported - uses axes acceleration. @@ -247,9 +269,11 @@ typedef struct _SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticCondition */ -#define SDL_HAPTIC_INERTIA (1u<<9) +#define SDL_HAPTIC_INERTIA (1u<<9) /** * Friction effect supported - uses axes movement. @@ -257,16 +281,52 @@ typedef struct _SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticCondition */ -#define SDL_HAPTIC_FRICTION (1u<<10) +#define SDL_HAPTIC_FRICTION (1u<<10) + +/** + * Left/Right effect supported. + * + * Haptic effect for direct control over high/low frequency motors. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticLeftRight + */ +#define SDL_HAPTIC_LEFTRIGHT (1u<<11) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAPTIC_RESERVED3 (1u<<14) /** * Custom effect is supported. * * User defined custom haptic effect. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_HAPTIC_CUSTOM (1u<<11) +#define SDL_HAPTIC_CUSTOM (1u<<15) /* @} *//* Haptic effects */ @@ -277,37 +337,45 @@ typedef struct _SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \sa SDL_HapticSetGain + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticGain */ -#define SDL_HAPTIC_GAIN (1u<<12) +#define SDL_HAPTIC_GAIN (1u<<16) /** * Device can set autocenter. * * Device supports setting autocenter. * - * \sa SDL_HapticSetAutocenter + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticAutocenter */ -#define SDL_HAPTIC_AUTOCENTER (1u<<13) +#define SDL_HAPTIC_AUTOCENTER (1u<<17) /** * Device can be queried for effect status. * * Device supports querying effect status. * - * \sa SDL_HapticGetEffectStatus + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetHapticEffectStatus */ -#define SDL_HAPTIC_STATUS (1u<<14) +#define SDL_HAPTIC_STATUS (1u<<18) /** * Device can be paused. * * Devices supports being paused. * - * \sa SDL_HapticPause - * \sa SDL_HapticUnpause + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PauseHaptic + * \sa SDL_ResumeHaptic */ -#define SDL_HAPTIC_PAUSE (1u<<15) +#define SDL_HAPTIC_PAUSE (1u<<19) /** @@ -318,6 +386,8 @@ typedef struct _SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticDirection */ #define SDL_HAPTIC_POLAR 0 @@ -325,6 +395,8 @@ typedef struct _SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticDirection */ #define SDL_HAPTIC_CARTESIAN 1 @@ -332,6 +404,8 @@ typedef struct _SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticDirection */ #define SDL_HAPTIC_SPHERICAL 2 @@ -342,6 +416,8 @@ typedef struct _SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * + * \since This macro is available since SDL 3.2.0. + * * \sa SDL_HapticDirection */ #define SDL_HAPTIC_STEERING_AXIS 3 @@ -357,7 +433,9 @@ typedef struct _SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \sa SDL_HapticRunEffect + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect */ #define SDL_HAPTIC_INFINITY 4294967295U @@ -456,12 +534,14 @@ typedef struct _SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN * \sa SDL_HAPTIC_SPHERICAL * \sa SDL_HAPTIC_STEERING_AXIS * \sa SDL_HapticEffect - * \sa SDL_HapticNumAxes + * \sa SDL_GetNumHapticAxes */ typedef struct SDL_HapticDirection { @@ -478,6 +558,8 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect */ @@ -558,8 +640,10 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_SINE - * \sa SDL_HAPTIC_LEFTRIGHT + * \sa SDL_HAPTIC_SQUARE * \sa SDL_HAPTIC_TRIANGLE * \sa SDL_HAPTIC_SAWTOOTHUP * \sa SDL_HAPTIC_SAWTOOTHDOWN @@ -568,7 +652,7 @@ typedef struct SDL_HapticConstant typedef struct SDL_HapticPeriodic { /* Header */ - Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT, + Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HapticDirection direction; /**< Direction of the effect. */ @@ -612,6 +696,8 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING * \sa SDL_HAPTIC_DAMPER @@ -653,6 +739,8 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect */ @@ -690,6 +778,8 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect */ @@ -718,6 +808,8 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect */ @@ -811,6 +903,8 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * + * \since This struct is available since SDL 3.2.0. + * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic * \sa SDL_HapticCondition @@ -830,36 +924,52 @@ typedef union SDL_HapticEffect SDL_HapticCustom custom; /**< Custom effect. */ } SDL_HapticEffect; +/** + * This is a unique ID for a haptic device for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the haptic device is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_HapticID; + /* Function prototypes */ /** - * Count the number of haptic devices attached to the system. + * Get a list of currently connected haptic devices. * - * \returns the number of haptic devices detected on the system or a negative - * error code on failure; call SDL_GetError() for more information. + * \param count a pointer filled in with the number of haptic devices + * returned, may be NULL. + * \returns a 0 terminated array of haptic device instance IDs or NULL on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticName + * \sa SDL_OpenHaptic */ -extern DECLSPEC int SDLCALL SDL_NumHaptics(void); +extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); /** * Get the implementation dependent name of a haptic device. * - * This can be called before any joysticks are opened. If no name can be - * found, this function returns NULL. + * This can be called before any haptic devices are opened. * - * \param device_index index of the device to query. - * \returns the name of the device or NULL on failure; call SDL_GetError() for - * more information. + * \param instance_id the haptic device instance ID. + * \returns the name of the selected haptic device. If no name can be found, + * this function returns NULL; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_NumHaptics + * \sa SDL_GetHapticName + * \sa SDL_OpenHaptic */ -extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID instance_id); /** * Open a haptic device for use. @@ -868,64 +978,71 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); * system. * * When opening a haptic device, its gain will be set to maximum and - * autocenter will be disabled. To modify these values use SDL_HapticSetGain() - * and SDL_HapticSetAutocenter(). + * autocenter will be disabled. To modify these values use SDL_SetHapticGain() + * and SDL_SetHapticAutocenter(). * - * \param device_index index of the device to open. + * \param instance_id the haptic device instance ID. * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticClose - * \sa SDL_HapticIndex - * \sa SDL_HapticOpenFromJoystick - * \sa SDL_HapticOpenFromMouse - * \sa SDL_HapticPause - * \sa SDL_HapticSetAutocenter - * \sa SDL_HapticSetGain - * \sa SDL_HapticStopAll + * \sa SDL_CloseHaptic + * \sa SDL_GetHaptics + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_OpenHapticFromMouse + * \sa SDL_SetHapticAutocenter + * \sa SDL_SetHapticGain */ -extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index); +extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id); + /** - * Check if the haptic device at the designated index has been opened. + * Get the SDL_Haptic associated with an instance ID, if it has been opened. * - * \param device_index the index of the device to query. - * \returns 1 if it has been opened, 0 if it hasn't or on failure; call - * SDL_GetError() for more information. + * \param instance_id the instance ID to get the SDL_Haptic for. + * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been + * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_HapticIndex - * \sa SDL_HapticOpen + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index); +extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); /** - * Get the index of a haptic device. + * Get the instance ID of an opened haptic device. * * \param haptic the SDL_Haptic device to query. - * \returns the index of the specified haptic device or a negative error code - * on failure; call SDL_GetError() for more information. + * \returns the instance ID of the specified haptic device on success or 0 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); + +/** + * Get the implementation dependent name of a haptic device. + * + * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick(). + * \returns the name of the selected haptic device. If no name can be found, + * this function returns NULL; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpen - * \sa SDL_HapticOpened + * \sa SDL_GetHapticNameForID */ -extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpenFromMouse + * \sa SDL_OpenHapticFromMouse */ -extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -933,26 +1050,24 @@ extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpen - * \sa SDL_MouseIsHaptic + * \sa SDL_CloseHaptic + * \sa SDL_IsMouseHaptic */ -extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void); +extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); /** * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a - * negative error code on failure; call SDL_GetError() for more - * information. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpenFromJoystick + * \sa SDL_OpenHapticFromJoystick */ -extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -969,43 +1084,41 @@ extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick); * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticClose - * \sa SDL_HapticOpen - * \sa SDL_JoystickIsHaptic + * \sa SDL_CloseHaptic + * \sa SDL_IsJoystickHaptic */ -extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * - joystick); +extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick *joystick); /** - * Close a haptic device previously opened with SDL_HapticOpen(). + * Close a haptic device previously opened with SDL_OpenHaptic(). * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpen + * \sa SDL_OpenHaptic */ -extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic); +extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); /** * Get the number of effects a haptic device can store. * * On some platforms this isn't fully supported, and therefore is an * approximation. Always check to see if your created effect was actually - * created and do not rely solely on SDL_HapticNumEffects(). + * created and do not rely solely on SDL_GetMaxHapticEffects(). * * \param haptic the SDL_Haptic device to query. * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticNumEffectsPlaying - * \sa SDL_HapticQuery + * \sa SDL_GetMaxHapticEffectsPlaying + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); +extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); /** * Get the number of effects a haptic device can play at the same time. @@ -1014,15 +1127,14 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); * * \param haptic the SDL_Haptic device to query maximum playing effects. * \returns the number of effects the haptic device can play at the same time - * or a negative error code on failure; call SDL_GetError() for more - * information. + * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticNumEffects - * \sa SDL_HapticQuery + * \sa SDL_GetMaxHapticEffects + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); +extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *haptic); /** * Get the haptic device's supported features in bitwise manner. @@ -1031,13 +1143,12 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported - * \sa SDL_HapticNumEffects + * \sa SDL_GetMaxHapticEffects */ -extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic); - +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); /** * Get the number of haptic axes the device has. @@ -1046,30 +1157,26 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic); * SDL_HapticDirection effect. * * \param haptic the SDL_Haptic device to query. - * \returns the number of axes on success or a negative error code on failure; - * call SDL_GetError() for more information. + * \returns the number of axes on success or -1 on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); /** * Check to see if an effect is supported by a haptic device. * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a - * negative error code on failure; call SDL_GetError() for more - * information. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticNewEffect - * \sa SDL_HapticQuery + * \sa SDL_CreateHapticEffect + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, - SDL_HapticEffect * - effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1077,17 +1184,16 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, * \param haptic an SDL_Haptic device to create the effect on. * \param effect an SDL_HapticEffect structure containing the properties of * the effect to create. - * \returns the ID of the effect on success or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the ID of the effect on success or -1 on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticDestroyEffect - * \sa SDL_HapticRunEffect - * \sa SDL_HapticUpdateEffect + * \sa SDL_DestroyHapticEffect + * \sa SDL_RunHapticEffect + * \sa SDL_UpdateHapticEffect */ -extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, - SDL_HapticEffect * effect); +extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Update the properties of an effect. @@ -1095,24 +1201,21 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, * Can be used dynamically, although behavior when dynamically changing * direction may be strange. Specifically the effect may re-upload itself and * start playing from the start. You also cannot change the type either when - * running SDL_HapticUpdateEffect(). + * running SDL_UpdateHapticEffect(). * * \param haptic the SDL_Haptic device that has the effect. * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticDestroyEffect - * \sa SDL_HapticNewEffect - * \sa SDL_HapticRunEffect + * \sa SDL_CreateHapticEffect + * \sa SDL_RunHapticEffect */ -extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, - int effect, - SDL_HapticEffect * data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1127,36 +1230,31 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticDestroyEffect - * \sa SDL_HapticGetEffectStatus - * \sa SDL_HapticStopEffect + * \sa SDL_GetHapticEffectStatus + * \sa SDL_StopHapticEffect + * \sa SDL_StopHapticEffects */ -extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, - int effect, - Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * - * * - * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticDestroyEffect - * \sa SDL_HapticRunEffect + * \sa SDL_RunHapticEffect + * \sa SDL_StopHapticEffects */ -extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, - int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1167,12 +1265,11 @@ extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticNewEffect + * \sa SDL_CreateHapticEffect */ -extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, - int effect); +extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int effect); /** * Get the status of the current effect on the specified haptic device. @@ -1181,16 +1278,14 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns 0 if it isn't playing, 1 if it is playing, or a negative error - * code on failure; call SDL_GetError() for more information. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticRunEffect - * \sa SDL_HapticStopEffect + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, - int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1199,20 +1294,20 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, * * The user may specify the maximum gain by setting the environment variable * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to - * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the + * SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the * maximum. * * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticQuery + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1224,92 +1319,89 @@ extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain); * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticQuery + * \sa SDL_GetHapticFeatures */ -extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, - int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. * - * Device must support the `SDL_HAPTIC_PAUSE` feature. Call - * SDL_HapticUnpause() to resume playback. + * Device must support the `SDL_HAPTIC_PAUSE` feature. Call SDL_ResumeHaptic() + * to resume playback. * * Do not modify the effects nor add new ones while the device is paused. That * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticUnpause + * \sa SDL_ResumeHaptic */ -extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** - * Unpause a haptic device. + * Resume a haptic device. * - * Call to unpause after SDL_HapticPause(). + * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticPause + * \sa SDL_PauseHaptic */ -extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * - * \since This function is available since SDL 2.0.0. + * \sa SDL_RunHapticEffect + * \sa SDL_StopHapticEffects */ -extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a - * negative error code on failure; call SDL_GetError() for more - * information. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticRumbleInit - * \sa SDL_HapticRumblePlay - * \sa SDL_HapticRumbleStop + * \sa SDL_InitHapticRumble */ -extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticOpen - * \sa SDL_HapticRumblePlay - * \sa SDL_HapticRumbleStop + * \sa SDL_PlayHapticRumble + * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1317,38 +1409,33 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticRumbleInit - * \sa SDL_HapticRumbleStop - * \sa SDL_HapticRumbleSupported + * \sa SDL_InitHapticRumble + * \sa SDL_StopHapticRumble */ -extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length ); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_HapticRumbleInit - * \sa SDL_HapticRumblePlay - * \sa SDL_HapticRumbleSupported + * \sa SDL_PlayHapticRumble */ -extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_haptic_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hidapi.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hidapi.h new file mode 100644 index 0000000000..131b03723a --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hidapi.h @@ -0,0 +1,552 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: HIDAPI */ + +/** + * # CategoryHIDAPI + * + * Header file for SDL HIDAPI functions. + * + * This is an adaptation of the original HIDAPI interface by Alan Ott, and + * includes source code licensed under the following license: + * + * ``` + * HIDAPI - Multi-Platform library for + * communication with HID devices. + * + * Copyright 2009, Alan Ott, Signal 11 Software. + * All Rights Reserved. + * + * This software may be used by anyone for any reason so + * long as the copyright notice in the source files + * remains intact. + * ``` + * + * (Note that this license is the same as item three of SDL's zlib license, so + * it adds no new requirements on the user.) + * + * If you would like a version of SDL without this code, you can build SDL + * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for + * example on iOS or tvOS to avoid a dependency on the CoreBluetooth + * framework. + */ + +#ifndef SDL_hidapi_h_ +#define SDL_hidapi_h_ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing an open HID device. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_hid_device SDL_hid_device; + +/** + * HID underlying bus types. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_hid_bus_type { + /** Unknown bus type */ + SDL_HID_API_BUS_UNKNOWN = 0x00, + + /** USB bus + Specifications: + https://usb.org/hid */ + SDL_HID_API_BUS_USB = 0x01, + + /** Bluetooth or Bluetooth LE bus + Specifications: + https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/ + https://www.bluetooth.com/specifications/specs/hid-service-1-0/ + https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */ + SDL_HID_API_BUS_BLUETOOTH = 0x02, + + /** I2C bus + Specifications: + https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */ + SDL_HID_API_BUS_I2C = 0x03, + + /** SPI bus + Specifications: + https://www.microsoft.com/download/details.aspx?id=103325 */ + SDL_HID_API_BUS_SPI = 0x04 + +} SDL_hid_bus_type; + +/** hidapi info structure */ + +/** + * Information about a connected HID device + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_hid_device_info +{ + /** Platform-specific device path */ + char *path; + /** Device Vendor ID */ + unsigned short vendor_id; + /** Device Product ID */ + unsigned short product_id; + /** Serial Number */ + wchar_t *serial_number; + /** Device Release Number in binary-coded decimal, + also known as Device Version Number */ + unsigned short release_number; + /** Manufacturer String */ + wchar_t *manufacturer_string; + /** Product string */ + wchar_t *product_string; + /** Usage Page for this Device/Interface + (Windows/Mac/hidraw only) */ + unsigned short usage_page; + /** Usage for this Device/Interface + (Windows/Mac/hidraw only) */ + unsigned short usage; + /** The USB interface which this logical device + represents. + + Valid only if the device is a USB HID device. + Set to -1 in all other cases. + */ + int interface_number; + + /** Additional information about the USB interface. + Valid on libusb and Android implementations. */ + int interface_class; + int interface_subclass; + int interface_protocol; + + /** Underlying bus type */ + SDL_hid_bus_type bus_type; + + /** Pointer to the next device */ + struct SDL_hid_device_info *next; + +} SDL_hid_device_info; + + +/** + * Initialize the HIDAPI library. + * + * This function initializes the HIDAPI library. Calling it is not strictly + * necessary, as it will be called automatically by SDL_hid_enumerate() and + * any of the SDL_hid_open_*() functions if it is needed. This function should + * be called at the beginning of execution however, if there is a chance of + * HIDAPI handles being opened by different threads simultaneously. + * + * Each call to this function should have a matching call to SDL_hid_exit() + * + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_exit + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); + +/** + * Finalize the HIDAPI library. + * + * This function frees all of the static data associated with HIDAPI. It + * should be called at the end of execution to avoid memory leaks. + * + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_init + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); + +/** + * Check to see if devices may have been added or removed. + * + * Enumerating the HID devices is an expensive operation, so you can call this + * to see if there have been any system device changes since the last call to + * this function. A change in the counter returned doesn't necessarily mean + * that anything has changed, but you can call SDL_hid_enumerate() to get an + * updated device list. + * + * Calling this function for the first time may cause a thread or other system + * resource to be allocated to track device change notifications. + * + * \returns a change counter that is incremented with each potential device + * change, or 0 if device change detection isn't available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_enumerate + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); + +/** + * Enumerate the HID Devices. + * + * This function returns a linked list of all the HID devices attached to the + * system which match vendor_id and product_id. If `vendor_id` is set to 0 + * then any vendor matches. If `product_id` is set to 0 then any product + * matches. If `vendor_id` and `product_id` are both set to 0, then all HID + * devices will be returned. + * + * By default SDL will only enumerate controllers, to reduce risk of hanging + * or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS + * can be set to "0" to enumerate all HID devices. + * + * \param vendor_id the Vendor ID (VID) of the types of device to open, or 0 + * to match any vendor. + * \param product_id the Product ID (PID) of the types of device to open, or 0 + * to match any product. + * \returns a pointer to a linked list of type SDL_hid_device_info, containing + * information about the HID devices attached to the system, or NULL + * in the case of failure. Free this linked list by calling + * SDL_hid_free_enumeration(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_device_change_count + */ +extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id); + +/** + * Free an enumeration linked list. + * + * This function frees a linked list created by SDL_hid_enumerate(). + * + * \param devs pointer to a list of struct_device returned from + * SDL_hid_enumerate(). + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); + +/** + * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally + * a serial number. + * + * If `serial_number` is NULL, the first device with the specified VID and PID + * is opened. + * + * \param vendor_id the Vendor ID (VID) of the device to open. + * \param product_id the Product ID (PID) of the device to open. + * \param serial_number the Serial Number of the device to open (Optionally + * NULL). + * \returns a pointer to a SDL_hid_device object on success or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); + +/** + * Open a HID device by its path name. + * + * The path name be determined by calling SDL_hid_enumerate(), or a + * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). + * + * \param path the path name of the device to open. + * \returns a pointer to a SDL_hid_device object on success or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); + +/** + * Write an Output report to a HID device. + * + * The first byte of `data` must contain the Report ID. For devices which only + * support a single report, this must be set to 0x0. The remaining bytes + * contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_write() will always contain one more byte than the report contains. + * For example, if a hid report is 16 bytes long, 17 bytes must be passed to + * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), + * followed by the report data (16 bytes). In this example, the length passed + * in would be 17. + * + * SDL_hid_write() will send the data on the first OUT endpoint, if one + * exists. If it does not, it will send the data through the Control Endpoint + * (Endpoint 0). + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data the data to send, including the report number as the first + * byte. + * \param length the length in bytes of the data to send. + * \returns the actual number of bytes written and -1 on on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); + +/** + * Read an Input report from a HID device with timeout. + * + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into. + * \param length the number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. + * \param milliseconds timeout in milliseconds or -1 for blocking wait. + * \returns the actual number of bytes read and -1 on on failure; call + * SDL_GetError() for more information. If no packet was available to + * be read within the timeout period, this function returns 0. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); + +/** + * Read an Input report from a HID device. + * + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into. + * \param length the number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. + * \returns the actual number of bytes read and -1 on failure; call + * SDL_GetError() for more information. If no packet was available to + * be read and the handle is in non-blocking mode, this function + * returns 0. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); + +/** + * Set the device handle to be non-blocking. + * + * In non-blocking mode calls to SDL_hid_read() will return immediately with a + * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read() + * will wait (block) until there is data to read before returning. + * + * Nonblocking can be turned on and off at any time. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param nonblock enable or not the nonblocking reads - 1 to enable + * nonblocking - 0 to disable nonblocking. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); + +/** + * Send a Feature report to the device. + * + * Feature reports are sent over the Control endpoint as a Set_Report + * transfer. The first byte of `data` must contain the Report ID. For devices + * which only support a single report, this must be set to 0x0. The remaining + * bytes contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_send_feature_report() will always contain one more byte than the + * report contains. For example, if a hid report is 16 bytes long, 17 bytes + * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for + * devices which do not use numbered reports), followed by the report data (16 + * bytes). In this example, the length passed in would be 17. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data the data to send, including the report number as the first + * byte. + * \param length the length in bytes of the data to send, including the report + * number. + * \returns the actual number of bytes written and -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); + +/** + * Get a feature report from a HID device. + * + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length the number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); + +/** + * Get an input report from a HID device. + * + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length the number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); + +/** + * Close a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); + +/** + * Get The Manufacturer String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); + +/** + * Get The Product String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); + +/** + * Get The Serial Number String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); + +/** + * Get a string from a HID device, based on its string index. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string_index the index of the string to get. + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); + +/** + * Get the device info from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \returns a pointer to the SDL_hid_device_info for this hid_device or NULL + * on failure; call SDL_GetError() for more information. This struct + * is valid until the device is closed with SDL_hid_close(). + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); + +/** + * Get a report descriptor from a HID device. + * + * User has to provide a preallocated buffer where descriptor will be copied + * to. The recommended size for a preallocated buffer is 4096 bytes. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param buf the buffer to copy descriptor into. + * \param buf_size the size of the buffer in bytes. + * \returns the number of bytes actually copied or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); + +/** + * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. + * + * \param active true to start the scan, false to stop the scan. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_hidapi_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hints.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hints.h new file mode 100644 index 0000000000..a081535716 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_hints.h @@ -0,0 +1,4486 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryHints + * + * This file contains functions to set and get configuration hints, as well as + * listing each of them alphabetically. + * + * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the + * environment variable that can be used to override the default. + * + * In general these hints are just that - they may or may not be supported or + * applicable on any given platform, but they provide a way for an application + * or user to give the library a hint as to how they would like the library to + * work. + */ + +#ifndef SDL_hints_h_ +#define SDL_hints_h_ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Specify the behavior of Alt+Tab while the keyboard is grabbed. + * + * By default, SDL emulates Alt+Tab functionality while the keyboard is + * grabbed and your window is full-screen. This prevents the user from getting + * stuck in your application if you've enabled keyboard grab. + * + * The variable can be set to the following values: + * + * - "0": SDL will not handle Alt+Tab. Your application is responsible for + * handling Alt+Tab while the keyboard is grabbed. + * - "1": SDL will minimize your window when Alt+Tab is pressed (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" + +/** + * A variable to control whether the SDL activity is allowed to be re-created. + * + * If this hint is true, the activity can be recreated on demand by the OS, + * and Java static data and C++ static data remain with their current values. + * If this hint is false, then SDL will call exit() when you return from your + * main function and the application will be terminated and then started fresh + * each time. + * + * The variable can be set to the following values: + * + * - "0": The application starts fresh at each launch. (default) + * - "1": The application activity can be recreated by the OS. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" + +/** + * A variable to control whether the event loop will block itself when the app + * is paused. + * + * The variable can be set to the following values: + * + * - "0": Non blocking. + * - "1": Blocking. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" + +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + +/** + * A variable to control whether we trap the Android back button to handle it + * manually. + * + * This is necessary for the right mouse button to work on some Android + * devices, or to be able to trap the back button for use in your code + * reliably. If this hint is true, the back button will show up as an + * SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of + * SDL_SCANCODE_AC_BACK. + * + * The variable can be set to the following values: + * + * - "0": Back button will be handled as usual for system. (default) + * - "1": Back button will be trapped, allowing you to handle the key press + * manually. (This will also let right mouse click work on systems where the + * right mouse button functions as back.) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" + +/** + * A variable setting the app ID string. + * + * This string is used by desktop compositors to identify and group windows + * together, as well as match applications with associated desktop settings + * and icons. + * + * This will override SDL_PROP_APP_METADATA_IDENTIFIER_STRING, if set by the + * application. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_APP_ID "SDL_APP_ID" + +/** + * A variable setting the application name. + * + * This hint lets you specify the application name sent to the OS when + * required. For example, this will often appear in volume control applets for + * audio streams, and in lists of applications which are inhibiting the + * screensaver. You should use a string that describes your program ("My Game + * 2: The Revenge") + * + * This will override SDL_PROP_APP_METADATA_NAME_STRING, if set by the + * application. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_APP_NAME "SDL_APP_NAME" + +/** + * A variable controlling whether controllers used with the Apple TV generate + * UI events. + * + * When UI events are generated by controller input, the app will be + * backgrounded when the Apple TV remote's menu button is pressed, and when + * the pause or B buttons on gamepads are pressed. + * + * More information about properly making use of controllers for the Apple TV + * can be found here: + * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ + * + * The variable can be set to the following values: + * + * - "0": Controller input does not generate UI events. (default) + * - "1": Controller input generates UI events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" + +/** + * A variable controlling whether the Apple TV remote's joystick axes will + * automatically match the rotation of the remote. + * + * The variable can be set to the following values: + * + * - "0": Remote orientation does not affect joystick axes. (default) + * - "1": Joystick axes are based on the orientation of the remote. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" + +/** + * Specify the default ALSA audio device name. + * + * This variable is a specific audio device to open when the "default" audio + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" + +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + +/** + * A variable controlling the audio category on iOS and macOS. + * + * The variable can be set to the following values: + * + * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be + * muted by the phone mute switch (default) + * - "playback": Use the AVAudioSessionCategoryPlayback category. + * + * For more information, see Apple's documentation: + * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" + +/** + * A variable controlling the default audio channel count. + * + * If the application doesn't specify the audio channel count when opening the + * device, this hint can be used to specify a default channel count that will + * be used. This defaults to "1" for recording and "2" for playback devices. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" + +/** + * Specify an application icon name for an audio device. + * + * Some audio backends (such as Pulseaudio and Pipewire) allow you to set an + * XDG icon name for your application. Among other things, this icon might + * show up in a system control panel that lets the user adjust the volume on + * specific audio streams instead of using one giant master volume slider. + * Note that this is unrelated to the icon used by the windowing system, which + * may be set with SDL_SetWindowIcon (or via desktop file on Wayland). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default, "applications-games", which is likely to be installed. See + * https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html + * and + * https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html + * for the relevant XDG icon specs. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" + +/** + * A variable controlling device buffer size. + * + * This hint is an integer > 0, that represents the size of the device's + * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes per + * sample frame, for example). + * + * SDL3 generally decides this value on behalf of the app, but if for some + * reason the app needs to dictate this (because they want either lower + * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might + * require of the app), they can specify it. + * + * SDL will try to accommodate this value, but there is no promise you'll get + * the buffer size requested. Many platforms won't honor this request at all, + * or might adjust it. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" + +/** + * Specify an audio stream name for an audio device. + * + * Some audio backends (such as PulseAudio) allow you to describe your audio + * stream. Among other things, this description might show up in a system + * control panel that lets the user adjust the volume on specific audio + * streams instead of using one giant master volume slider. + * + * This hints lets you transmit that information to the OS. The contents of + * this hint are used while opening an audio device. You should use a string + * that describes your what your program is playing ("audio stream" is + * probably sufficient in many cases, but this could be useful for something + * like "team chat" if you have a headset playing VoIP audio separately). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "audio stream" or something similar. + * + * Note that while this talks about audio streams, this is an OS-level + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" + +/** + * Specify an application role for an audio device. + * + * Some audio backends (such as Pipewire) allow you to describe the role of + * your audio stream. Among other things, this description might show up in a + * system control panel or software for displaying and manipulating media + * playback/recording graphs. + * + * This hints lets you transmit that information to the OS. The contents of + * this hint are used while opening an audio device. You should use a string + * that describes your what your program is playing (Game, Music, Movie, + * etc...). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "Game" or something similar. + * + * Note that while this talks about audio streams, this is an OS-level + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" + +/** + * Specify the input file when recording audio using the disk audio driver. + * + * This defaults to "sdlaudio-in.raw" + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" + +/** + * Specify the output file when playing audio using the disk audio driver. + * + * This defaults to "sdlaudio.raw" + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" + +/** + * A variable controlling the audio rate when using the disk audio driver. + * + * The disk audio driver normally simulates real-time for the audio rate that + * was specified, but you can use this variable to adjust this rate higher or + * lower down to 0. The default value is "1.0". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" + +/** + * A variable that specifies an audio backend to use. + * + * By default, SDL will try all available audio backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific driver, such as "pipewire" if, say, you are on PulseAudio + * but want to try talking to the lower level instead. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" + +/** + * A variable controlling the audio rate when using the dummy audio driver. + * + * The dummy audio driver normally simulates real-time for the audio rate that + * was specified, but you can use this variable to adjust this rate higher or + * lower down to 0. The default value is "1.0". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" + +/** + * A variable controlling the default audio format. + * + * If the application doesn't specify the audio format when opening the + * device, this hint can be used to specify a default format that will be + * used. + * + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" + +/** + * A variable controlling the default audio frequency. + * + * If the application doesn't specify the audio frequency when opening the + * device, this hint can be used to specify a default frequency that will be + * used. This defaults to "44100". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" + +/** + * A variable that causes SDL to not ignore audio "monitors". + * + * This is currently only used by the PulseAudio driver. + * + * By default, SDL ignores audio devices that aren't associated with physical + * hardware. Changing this hint to "1" will expose anything SDL sees that + * appears to be an audio source or sink. This will add "devices" to the list + * that the user probably doesn't want or need, but it can be useful in + * scenarios where you want to hook up SDL to some sort of virtual device, + * etc. + * + * The variable can be set to the following values: + * + * - "0": Audio monitor devices will be ignored. (default) + * - "1": Audio monitor devices will show up in the device list. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" + +/** + * A variable controlling whether SDL updates joystick state when getting + * input events. + * + * The variable can be set to the following values: + * + * - "0": You'll call SDL_UpdateJoysticks() manually. + * - "1": SDL will automatically call SDL_UpdateJoysticks(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" + +/** + * A variable controlling whether SDL updates sensor state when getting input + * events. + * + * The variable can be set to the following values: + * + * - "0": You'll call SDL_UpdateSensors() manually. + * - "1": SDL will automatically call SDL_UpdateSensors(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" + +/** + * Prevent SDL from using version 4 of the bitmap header when saving BMPs. + * + * The bitmap header version 4 is required for proper alpha channel support + * and SDL will use it when required. Should this not be desired, this hint + * can force the use of the 40 byte header version which is supported + * everywhere. + * + * The variable can be set to the following values: + * + * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file with an alpha mask. SDL will use the bitmap header version 4 and + * set the alpha mask accordingly. (default) + * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file without an alpha mask. The alpha channel data will be in the + * file, but applications are going to ignore it. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" + +/** + * A variable that decides what camera backend to use. + * + * By default, SDL will try all available camera backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "directshow" if, say, you are on + * Windows Media Foundations but want to try DirectShow instead. + * + * The default value is unset, in which case SDL will try to figure out the + * best camera backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" + +/** + * A variable that limits what CPU features are available. + * + * By default, SDL marks all features the current CPU supports as available. + * This hint allows to limit these to a subset. + * + * When the hint is unset, or empty, SDL will enable all detected CPU + * features. + * + * The variable can be set to a comma separated list containing the following + * items: + * + * - "all" + * - "altivec" + * - "sse" + * - "sse2" + * - "sse3" + * - "sse41" + * - "sse42" + * - "avx" + * - "avx2" + * - "avx512f" + * - "arm-simd" + * - "neon" + * - "lsx" + * - "lasx" + * + * The items can be prefixed by '+'/'-' to add/remove features. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" + +/** + * A variable controlling whether DirectInput should be used for controllers. + * + * The variable can be set to the following values: + * + * - "0": Disable DirectInput detection. + * - "1": Enable DirectInput detection. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" + +/** + * A variable that specifies a dialog backend to use. + * + * By default, SDL will try all available dialog backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target. + * + * If the specified target does not exist or is not available, the + * dialog-related function calls will fail. + * + * This hint currently only applies to platforms using the generic "Unix" + * dialog implementation, but may be extended to more platforms in the future. + * Note that some Unix and Unix-like platforms have their own implementation, + * such as macOS and Haiku. + * + * The variable can be set to the following values: + * + * - NULL: Select automatically (default, all platforms) + * - "portal": Use XDG Portals through DBus (Unix only) + * - "zenity": Use the Zenity program (Unix only) + * + * More options may be added in the future. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" + +/** + * Override for SDL_GetDisplayUsableBounds(). + * + * If set, this hint will override the expected results for + * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want + * to do this, but this allows an embedded system to request that some of the + * screen be reserved for other uses when paired with a well-behaved + * application. + * + * The contents of this hint must be 4 comma-separated integers, the first is + * the bounds x, then y, width and height, in that order. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" + +/** + * Disable giving back control to the browser automatically when running with + * asyncify. + * + * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as + * refreshing the screen or polling events. + * + * This hint only applies to the emscripten platform. + * + * The variable can be set to the following values: + * + * - "0": Disable emscripten_sleep calls (if you give back browser control + * manually or use asyncify for other purposes). + * - "1": Enable emscripten_sleep calls. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" + +/** + * Specify the CSS selector used for the "default" window/canvas. + * + * This hint only applies to the emscripten platform. + * + * The default value is "#canvas" + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" + +/** + * Override the binding element for keyboard inputs for Emscripten builds. + * + * This hint only applies to the emscripten platform. + * + * The variable can be one of: + * + * - "#window": the javascript window object (default) + * - "#document": the javascript document object + * - "#screen": the javascript window.screen object + * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all + * - any other string without a leading # sign applies to the element on the + * page with that ID. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" + +/** + * A variable that controls whether the on-screen keyboard should be shown + * when text input is active. + * + * The variable can be set to the following values: + * + * - "auto": The on-screen keyboard will be shown if there is no physical + * keyboard attached. (default) + * - "0": Do not show the on-screen keyboard. + * - "1": Show the on-screen keyboard, if available. + * + * This hint must be set before SDL_StartTextInput() is called + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" + +/** + * A variable containing a list of evdev devices to use if udev is not + * available. + * + * The list of devices is in the form: + * + * deviceclass:path[,deviceclass:path[,...]] + * + * where device class is an integer representing the SDL_UDEV_deviceclass and + * path is the full path to the event device. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" + +/** + * A variable controlling verbosity of the logging of SDL events pushed onto + * the internal queue. + * + * The variable can be set to the following values, from least to most + * verbose: + * + * - "0": Don't log any events. (default) + * - "1": Log most events (other than the really spammy ones). + * - "2": Include mouse and finger motion events. + * + * This is generally meant to be used to debug SDL itself, but can be useful + * for application developers that need better visibility into what is going + * on in the event queue. Logged events are sent through SDL_Log(), which + * means by default they appear on stdout on most platforms or maybe + * OutputDebugString() on Windows, and can be funneled by the app with + * SDL_SetLogOutputFunction(), etc. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" + +/** + * A variable controlling whether raising the window should be done more + * forcefully. + * + * The variable can be set to the following values: + * + * - "0": Honor the OS policy for raising windows. (default) + * - "1": Force the window to be raised, overriding any OS policy. + * + * At present, this is only an issue under MS Windows, which makes it nearly + * impossible to programmatically move a window to the foreground, for + * "security" reasons. See http://stackoverflow.com/a/34414846 for a + * discussion. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" + +/** + * A variable controlling how 3D acceleration is used to accelerate the SDL + * screen surface. + * + * SDL can try to accelerate the SDL screen surface by using streaming + * textures with a 3D rendering engine. This variable controls whether and how + * this is done. + * + * The variable can be set to the following values: + * + * - "0": Disable 3D acceleration + * - "1": Enable 3D acceleration, using the default renderer. (default) + * - "X": Enable 3D acceleration, using X where X is one of the valid + * rendering drivers. (e.g. "direct3d", "opengl", etc.) + * + * This hint should be set before calling SDL_GetWindowSurface() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" + +/** + * A variable that lets you manually hint extra gamecontroller db entries. + * + * The variable should be newline delimited rows of gamecontroller config + * data, see SDL_gamepad.h + * + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" + +/** + * A variable that lets you provide a file with extra gamecontroller db + * entries. + * + * The file should contain lines of gamecontroller config data, see + * SDL_gamepad.h + * + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" + +/** + * A variable that overrides the automatic controller type detection. + * + * The variable should be comma separated entries, in the form: VID/PID=type + * + * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd + * + * This hint affects what low level protocol is used with the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "Xbox360" + * - "XboxOne" + * - "PS3" + * - "PS4" + * - "PS5" + * - "SwitchPro" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" + +/** + * A variable containing a list of devices to skip when scanning for game + * controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" + +/** + * If set, all devices will be skipped when scanning for game controllers + * except for the ones listed in this variable. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" + +/** + * A variable that controls whether the device's built-in accelerometer and + * gyro should be used as sensors for gamepads. + * + * The variable can be set to the following values: + * + * - "0": Sensor fusion is disabled + * - "1": Sensor fusion is enabled for all controllers that lack sensors + * + * Or the variable can be a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before a gamepad is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" + +/** + * This variable sets the default text of the TextInput window on GDK + * platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" + +/** + * This variable sets the description of the TextInput window on GDK + * platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" + +/** + * This variable sets the maximum input length of the TextInput window on GDK + * platforms. + * + * The value must be a stringified integer, for example "10" to allow for up + * to 10 characters of text input. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" + +/** + * This variable sets the input scope of the TextInput window on GDK + * platforms. + * + * Set this hint to change the XGameUiTextEntryInputScope value that will be + * passed to the window creation function. The value must be a stringified + * integer, for example "0" for XGameUiTextEntryInputScope::Default. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" + +/** + * This variable sets the title of the TextInput window on GDK platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" + +/** + * A variable to control whether HIDAPI uses libusb for device access. + * + * By default libusb will only be used for a few devices that require direct + * USB access, and this can be controlled with + * SDL_HINT_HIDAPI_LIBUSB_WHITELIST. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will not use libusb for device access. + * - "1": HIDAPI will use libusb for device access if available. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" + +/** + * A variable to control whether HIDAPI uses libusb only for whitelisted + * devices. + * + * By default libusb will only be used for a few devices that require direct + * USB access. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will use libusb for all device access. + * - "1": HIDAPI will use libusb only for whitelisted devices. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" + +/** + * A variable to control whether HIDAPI uses udev for device detection. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will poll for device changes. + * - "1": HIDAPI will use udev for device detection. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" + +/** + * A variable that specifies a GPU backend to use. + * + * By default, SDL will try all available GPU backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "direct3d12" if, say, your hardware + * supports Vulkan but you want to try using D3D12 instead. + * + * This hint should be set before any GPU functions are called. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" + +/** + * A variable to control whether SDL_hid_enumerate() enumerates all HID + * devices or only controllers. + * + * The variable can be set to the following values: + * + * - "0": SDL_hid_enumerate() will enumerate all HID devices. + * - "1": SDL_hid_enumerate() will only enumerate controllers. (default) + * + * By default SDL will only enumerate controllers, to reduce risk of hanging + * or crashing on devices with bad drivers and avoiding macOS keyboard capture + * permission prompts. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" + +/** + * A variable containing a list of devices to ignore in SDL_hid_enumerate(). + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * For example, to ignore the Shanwan DS3 controller and any Valve controller, + * you might use the string "0x2563/0x0523,0x28de/0x0000" + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" + +/** + * A variable describing what IME UI elements the application can display. + * + * By default IME UI is handled using native components by the OS where + * possible, however this can interfere with or not be visible when exclusive + * fullscreen mode is used. + * + * The variable can be set to a comma separated list containing the following + * items: + * + * - "none" or "0": The application can't render any IME elements, and native + * UI should be used. (default) + * - "composition": The application handles SDL_EVENT_TEXT_EDITING events and + * can render the composition text. + * - "candidates": The application handles SDL_EVENT_TEXT_EDITING_CANDIDATES + * and can render the candidate list. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" + +/** + * A variable controlling whether the home indicator bar on iPhone X should be + * hidden. + * + * The variable can be set to the following values: + * + * - "0": The indicator bar is not hidden. (default for windowed applications) + * - "1": The indicator bar is hidden and is shown when the screen is touched + * (useful for movie playback applications). + * - "2": The indicator bar is dim and the first swipe makes it visible and + * the second swipe performs the "home" action. (default for fullscreen + * applications) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" + +/** + * A variable that lets you enable joystick (and gamecontroller) events even + * when your app is in the background. + * + * The variable can be set to the following values: + * + * - "0": Disable joystick & gamecontroller input events when the application + * is in the background. (default) + * - "1": Enable joystick & gamecontroller input events when the application + * is in the background. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" + +/** + * A variable containing a list of arcade stick style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" + +/** + * A variable containing a list of devices that are not arcade stick style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" + +/** + * A variable containing a list of devices that should not be considered + * joysticks. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" + +/** + * A variable containing a list of devices that should be considered + * joysticks. + * + * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" + +/** + * A variable containing a comma separated list of devices to open as + * joysticks. + * + * This variable is currently only used by the Linux joystick driver. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" + +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + +/** + * A variable containing a list of flightstick style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" + +/** + * A variable containing a list of devices that are not flightstick style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" + +/** + * A variable controlling whether GameInput should be used for controller + * handling on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used. + * - "1": GameInput is used. + * + * The default is "1" on GDK platforms, and "0" otherwise. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" + +/** + * A variable containing a list of devices known to have a GameCube form + * factor. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" + +/** + * A variable containing a list of devices known not to have a GameCube form + * factor. + * + * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" + +/** + * A variable controlling whether the HIDAPI joystick drivers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI drivers are not used. + * - "1": HIDAPI drivers are used. (default) + * + * This variable is the default for all drivers, but can be overridden by the + * hints for specific drivers below. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" + +/** + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * combined into a single Pro-like controller when using the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be combined and each + * will be a mini-gamepad. + * - "1": Left and right Joy-Con controllers will be combined into a single + * controller. (default) + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" + +/** + * A variable controlling whether the HIDAPI driver for Nintendo GameCube + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" + +/** + * A variable controlling whether rumble is used to implement the GameCube + * controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2). + * + * This is useful for applications that need full compatibility for things + * like ADSR envelopes. - Stop is implemented by setting low_frequency_rumble + * to 0 and high_frequency_rumble >0 - Rumble is both at any arbitrary value - + * StopHard is implemented by setting both low_frequency_rumble and + * high_frequency_rumble to 0 + * + * The variable can be set to the following values: + * + * - "0": Normal rumble behavior is behavior is used. (default) + * - "1": Proper GameCube controller rumble behavior is used. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" + +/** + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * Joy-Cons should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" + +/** + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Joy-Con controller is opened. + * + * The variable can be set to the following values: + * + * - "0": home button LED is turned off + * - "1": home button LED is turned on + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" + +/** + * A variable controlling whether the HIDAPI driver for Amazon Luna + * controllers connected via Bluetooth should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" + +/** + * A variable controlling whether the HIDAPI driver for Nintendo Online + * classic controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" + +/** + * A variable controlling whether the HIDAPI driver for PS3 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on + * other platforms. + * + * For official Sony driver (sixaxis.sys) use + * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See + * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" + +/** + * A variable controlling whether the Sony driver (sixaxis.sys) for PS3 + * controllers (Sixaxis/DualShock 3) should be used. + * + * The variable can be set to the following values: + * + * - "0": Sony driver (sixaxis.sys) is not used. + * - "1": Sony driver (sixaxis.sys) is used. + * + * The default value is 0. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" + +/** + * A variable controlling whether the HIDAPI driver for PS4 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" + +/** + * A variable controlling the update rate of the PS4 controller over Bluetooth + * when using the HIDAPI driver. + * + * This defaults to 4 ms, to match the behavior over USB, and to be more + * friendly to other Bluetooth devices and older Bluetooth hardware on the + * computer. It can be set to "1" (1000Hz), "2" (500Hz) and "4" (250Hz) + * + * This hint can be set anytime, but only takes effect when extended input + * reports are enabled. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" + +/** + * A variable controlling whether the HIDAPI driver for PS5 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" + +/** + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a PS5 controller. + * + * The variable can be set to the following values: + * + * - "0": player LEDs are not enabled. + * - "1": player LEDs are enabled. (default) + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" + +/** + * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" + +/** + * A variable controlling whether the HIDAPI driver for Google Stadia + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" + +/** + * A variable controlling whether the HIDAPI driver for Bluetooth Steam + * Controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. (default) + * - "1": HIDAPI driver is used for Steam Controllers, which requires + * Bluetooth access and may prompt the user for permission on iOS and + * Android. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" + +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + +/** + * A variable controlling whether the HIDAPI driver for the Steam Deck builtin + * controller should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" + +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + +/** + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" + +/** + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Pro controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Home button LED is turned off. + * - "1": Home button LED is turned on. + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" + +/** + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Nintendo Switch controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" + +/** + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * in vertical mode when using the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be in vertical mode. + * (default) + * - "1": Left and right Joy-Con controllers will be in vertical mode. + * + * This hint should be set before opening a Joy-Con controller. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" + +/** + * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * This driver doesn't work with the dolphinbar, so the default is false for + * now. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" + +/** + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Wii controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" + +/** + * A variable controlling whether the HIDAPI driver for XBox controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is "0" on Windows, otherwise the value of + * SDL_HINT_JOYSTICK_HIDAPI + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" + +/** + * A variable controlling whether the HIDAPI driver for XBox 360 controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" + +/** + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with an Xbox 360 controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" + +/** + * A variable controlling whether the HIDAPI driver for XBox 360 wireless + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" + +/** + * A variable controlling whether the HIDAPI driver for XBox One controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" + +/** + * A variable controlling whether the Home button LED should be turned on when + * an Xbox One controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Home button LED is turned off. + * - "1": Home button LED is turned on. + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. The default brightness is 0.4. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" + +/** + * A variable controlling whether IOKit should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": IOKit is not used. + * - "1": IOKit is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" + +/** + * A variable controlling whether to use the classic /dev/input/js* joystick + * interface or the newer /dev/input/event* joystick interface on Linux. + * + * The variable can be set to the following values: + * + * - "0": Use /dev/input/event* (default) + * - "1": Use /dev/input/js* + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" + +/** + * A variable controlling whether joysticks on Linux adhere to their + * HID-defined deadzones or return unfiltered values. + * + * The variable can be set to the following values: + * + * - "0": Return unfiltered joystick axis values. (default) + * - "1": Return axis values with deadzones taken into account. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" + +/** + * A variable controlling whether joysticks on Linux will always treat 'hat' + * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking + * whether they may be analog. + * + * The variable can be set to the following values: + * + * - "0": Only map hat axis inputs to digital hat outputs if the input axes + * appear to actually be digital. (default) + * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as + * digital hats. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" + +/** + * A variable controlling whether digital hats on Linux will apply deadzones + * to their underlying input axes or use unfiltered values. + * + * The variable can be set to the following values: + * + * - "0": Return digital hat values based on unfiltered input axis values. + * - "1": Return digital hat values with deadzones on the input axes taken + * into account. (default) + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" + +/** + * A variable controlling whether GCController should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": GCController is not used. + * - "1": GCController is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" + +/** + * A variable controlling whether the RAWINPUT joystick drivers should be used + * for better handling XInput-capable devices. + * + * The variable can be set to the following values: + * + * - "0": RAWINPUT drivers are not used. (default) + * - "1": RAWINPUT drivers are used. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" + +/** + * A variable controlling whether the RAWINPUT driver should pull correlated + * data from XInput. + * + * The variable can be set to the following values: + * + * - "0": RAWINPUT driver will only use data from raw input APIs. + * - "1": RAWINPUT driver will also pull data from XInput and + * Windows.Gaming.Input, providing better trigger axes, guide button + * presses, and rumble support for Xbox controllers. (default) + * + * This hint should be set before a gamepad is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" + +/** + * A variable controlling whether the ROG Chakram mice should show up as + * joysticks. + * + * The variable can be set to the following values: + * + * - "0": ROG Chakram mice do not show up as joysticks. (default) + * - "1": ROG Chakram mice show up as joysticks. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" + +/** + * A variable controlling whether a separate thread should be used for + * handling joystick detection and raw input messages on Windows. + * + * The variable can be set to the following values: + * + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" + +/** + * A variable containing a list of throttle style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" + +/** + * A variable containing a list of devices that are not throttle style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" + +/** + * A variable controlling whether Windows.Gaming.Input should be used for + * controller handling. + * + * The variable can be set to the following values: + * + * - "0": WGI is not used. + * - "1": WGI is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" + +/** + * A variable containing a list of wheel style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" + +/** + * A variable containing a list of devices that are not wheel style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device + * list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" + +/** + * A variable containing a list of devices known to have all axes centered at + * zero. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" + +/** + * A variable containing a list of devices and their desired number of haptic + * (force feedback) enabled axis. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form plus the number of desired axes, e.g. + * + * `0xAAAA/0xBBBB/1,0xCCCC/0xDDDD/3` + * + * This hint supports a "wildcard" device that will set the number of haptic + * axes on all initialized haptic devices which were not defined explicitly in + * this hint. + * + * `0xFFFF/0xFFFF/1` + * + * This hint should be set before a controller is opened. The number of haptic + * axes won't exceed the number of real axes found on the device. + * + * \since This hint is available since SDL 3.2.5. + */ +#define SDL_HINT_JOYSTICK_HAPTIC_AXES "SDL_JOYSTICK_HAPTIC_AXES" + +/** + * A variable that controls keycode representation in keyboard events. + * + * This variable is a comma separated set of options for translating keycodes + * in events: + * + * - "none": Keycode options are cleared, this overrides other options. + * - "hide_numpad": The numpad keysyms will be translated into their + * non-numpad versions based on the current NumLock state. For example, + * SDLK_KP_4 would become SDLK_4 if SDL_KMOD_NUM is set in the event + * modifiers, and SDLK_LEFT if it is unset. + * - "french_numbers": The number row on French keyboards is inverted, so + * pressing the 1 key would yield the keycode SDLK_1, or '1', instead of + * SDLK_AMPERSAND, or '&' + * - "latin_letters": For keyboards using non-Latin letters, such as Russian + * or Thai, the letter keys generate keycodes as though it had an en_US + * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian + * keyboard would yield 'a' instead of a Cyrillic letter. + * + * The default value for this hint is "french_numbers,latin_letters" + * + * Some platforms like Emscripten only provide modified keycodes and the + * options are not used. + * + * These options do not affect the return value of SDL_GetKeyFromScancode() or + * SDL_GetScancodeFromKey(), they just apply to the keycode included in key + * events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" + +/** + * A variable that controls what KMSDRM device to use. + * + * SDL might open something like "/dev/dri/cardNN" to access KMSDRM + * functionality, where "NN" is a device index number. SDL makes a guess at + * the best index to use (usually zero), but the app or user can set this hint + * to a number between 0 and 99 to force selection. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" + +/** + * A variable that controls whether SDL requires DRM master access in order to + * initialize the KMSDRM video backend. + * + * The DRM subsystem has a concept of a "DRM master" which is a DRM client + * that has the ability to set planes, set cursor, etc. When SDL is DRM + * master, it can draw to the screen using the SDL rendering APIs. Without DRM + * master, SDL is still able to process input and query attributes of attached + * displays, but it cannot change display state or draw to the screen + * directly. + * + * In some cases, it can be useful to have the KMSDRM backend even if it + * cannot be used for rendering. An app may want to use SDL for input + * processing while using another rendering API (such as an MMAL overlay on + * Raspberry Pi) or using its own code to render to DRM overlays that SDL + * doesn't support. + * + * The variable can be set to the following values: + * + * - "0": SDL will allow usage of the KMSDRM backend without DRM master. + * - "1": SDL Will require DRM master to use the KMSDRM backend. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" + +/** + * A variable controlling the default SDL log levels. + * + * This variable is a comma separated set of category=level tokens that define + * the default logging levels for SDL applications. + * + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. + * + * The level can be a numeric level, one of "verbose", "debug", "info", + * "warn", "error", "critical", or "quiet" to disable that category. + * + * You can omit the category if you want to set the logging level for all + * categories. + * + * If this hint isn't set, the default log levels are equivalent to: + * + * `app=info,assert=warn,test=verbose,*=error` + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_LOGGING "SDL_LOGGING" + +/** + * A variable controlling whether to force the application to become the + * foreground process when launched on macOS. + * + * The variable can be set to the following values: + * + * - "0": The application is brought to the foreground when launched. + * (default) + * - "1": The application may remain in the background when launched. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" + +/** + * A variable that determines whether Ctrl+Click should generate a right-click + * event on macOS. + * + * The variable can be set to the following values: + * + * - "0": Ctrl+Click does not generate a right mouse button click event. + * (default) + * - "1": Ctrl+Click generated a right mouse button click event. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" + +/** + * A variable controlling whether dispatching OpenGL context updates should + * block the dispatching thread until the main thread finishes processing on + * macOS. + * + * The variable can be set to the following values: + * + * - "0": Dispatching OpenGL context updates will block the dispatching thread + * until the main thread finishes processing. (default) + * - "1": Dispatching OpenGL context updates will allow the dispatching thread + * to continue execution. + * + * Generally you want the default, but if you have OpenGL code in a background + * thread on a Mac, and the main thread hangs because it's waiting for that + * background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" + +/** + * A variable controlling whether the Option key on macOS should be remapped + * to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + +/** + * Request SDL_AppIterate() be called at a specific rate. + * + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. + * + * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, + * this hint is ignored. When the hint can be used, it is allowed to be + * changed at any time. + * + * This defaults to 0, and specifying NULL for the hint's value will restore + * the default. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" + +/** + * A variable controlling whether the mouse is captured while mouse buttons + * are pressed. + * + * The variable can be set to the following values: + * + * - "0": The mouse is not captured while mouse buttons are pressed. + * - "1": The mouse is captured while mouse buttons are pressed. + * + * By default the mouse is captured while mouse buttons are pressed so if the + * mouse is dragged outside the window, the application continues to receive + * mouse events until the button is released. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" + +/** + * A variable setting the double click radius, in pixels. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" + +/** + * A variable setting the double click time, in milliseconds. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" + +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + +/** + * A variable controlling whether warping a hidden mouse cursor will activate + * relative mouse mode. + * + * When this hint is set, the mouse cursor is hidden, and multiple warps to + * the window center occur within a short time period, SDL will emulate mouse + * warps using relative mouse mode. This can provide smoother and more + * reliable mouse motion for some older games, which continuously calculate + * the distance travelled by the mouse pointer and warp it back to the center + * of the window, rather than using relative mouse motion. + * + * Note that relative mouse mode may have different mouse acceleration + * behavior than pointer warps. + * + * If your application needs to repeatedly warp the hidden mouse cursor at a + * high-frequency for other purposes, it should disable this hint. + * + * The variable can be set to the following values: + * + * - "0": Attempts to warp the mouse will always be made. + * - "1": Some mouse warps will be emulated by forcing relative mouse mode. + * (default) + * + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" + +/** + * Allow mouse click events when clicking to focus an SDL window. + * + * The variable can be set to the following values: + * + * - "0": Ignore mouse clicks that activate a window. (default) + * - "1": Generate events for mouse clicks that activate a window. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" + +/** + * A variable setting the speed scale for mouse motion, in floating point, + * when the mouse is not in relative mode. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" + +/** + * A variable controlling whether relative mouse mode constrains the mouse to + * the center of the window. + * + * Constraining to the center of the window works better for FPS games and + * when the application is running over RDP. Constraining to the whole window + * works better for 2D games and increases the chance that the mouse will be + * in the correct position when using high DPI mice. + * + * The variable can be set to the following values: + * + * - "0": Relative mouse mode constrains the mouse to the window. + * - "1": Relative mouse mode constrains the mouse to the center of the + * window. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" + +/** + * A variable setting the scale for mouse motion, in floating point, when the + * mouse is in relative mode. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" + +/** + * A variable controlling whether the system mouse acceleration curve is used + * for relative mouse motion. + * + * The variable can be set to the following values: + * + * - "0": Relative mouse motion will be unscaled. (default) + * - "1": Relative mouse motion will be scaled using the system mouse + * acceleration curve. + * + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after + * system speed scale. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" + +/** + * A variable controlling whether a motion event should be generated for mouse + * warping in relative mode. + * + * The variable can be set to the following values: + * + * - "0": Warping the mouse will not generate a motion event in relative mode + * - "1": Warping the mouse will generate a motion event in relative mode + * + * By default warping the mouse will not generate motion events in relative + * mode. This avoids the application having to filter out large relative + * motion due to warping. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" + +/** + * A variable controlling whether the hardware cursor stays visible when + * relative mode is active. + * + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active + * + * Note that for systems without raw hardware inputs, relative mode is + * implemented using warping, so the hardware cursor will visibly warp between + * frames if this is enabled on those systems. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" + +/** + * A variable controlling whether mouse events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Mouse events will not generate touch events. (default for desktop + * platforms) + * - "1": Mouse events will generate touch events. (default for mobile + * platforms, such as Android and iOS) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" + +/** + * A variable controlling whether the keyboard should be muted on the console. + * + * Normally the keyboard is muted while SDL applications are running so that + * keyboard input doesn't show up as key strokes on the console. This hint + * allows you to turn that off for debugging purposes. + * + * The variable can be set to the following values: + * + * - "0": Allow keystrokes to go through to the console. + * - "1": Mute keyboard input so it doesn't show up on the console. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" + +/** + * Tell SDL not to catch the SIGINT or SIGTERM signals on POSIX platforms. + * + * The variable can be set to the following values: + * + * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a + * signal, convert it into an SDL_EVENT_QUIT event. (default) + * - "1": SDL will not install a signal handler at all. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" + +/** + * Specify the OpenGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" + +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + +/** + * A variable controlling what driver to use for OpenGL ES contexts. + * + * On some platforms, currently Windows and X11, OpenGL drivers may support + * creating contexts with an OpenGL ES profile. By default SDL uses these + * profiles, when available, otherwise it attempts to load an OpenGL ES + * library, e.g. that provided by the ANGLE project. This variable controls + * whether SDL follows this default behaviour or will always load an OpenGL ES + * library. + * + * Circumstances where this is useful include - Testing an app with a + * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those + * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses + * at link time by linking with the OpenGL ES library instead of querying them + * at run time with SDL_GL_GetProcAddress(). + * + * Caution: for an application to work with the default behaviour across + * different OpenGL drivers it must query the OpenGL ES function addresses at + * run time using SDL_GL_GetProcAddress(). + * + * This variable is ignored on most platforms because OpenGL ES is native or + * not supported. + * + * The variable can be set to the following values: + * + * - "0": Use ES profile of OpenGL, if available. (default) + * - "1": Load OpenGL ES library using the default library names. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" + +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + +/** + * A variable controlling which orientations are allowed on iOS/Android. + * + * In some circumstances it is necessary to be able to explicitly control + * which UI orientations are allowed. + * + * This variable is a space delimited list of the following values: + * + * - "LandscapeLeft" + * - "LandscapeRight" + * - "Portrait" + * - "PortraitUpsideDown" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" + +/** + * A variable controlling the use of a sentinel event when polling the event + * queue. + * + * When polling for events, SDL_PumpEvents is used to gather new events from + * devices. If a device keeps producing new events between calls to + * SDL_PumpEvents, a poll loop will become stuck until the new events stop. + * This is most noticeable when moving a high frequency mouse. + * + * The variable can be set to the following values: + * + * - "0": Disable poll sentinels. + * - "1": Enable poll sentinels. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" + +/** + * Override for SDL_GetPreferredLocales(). + * + * If set, this will be favored over anything the OS might report for the + * user's preferred locales. Changing this hint at runtime will not generate a + * SDL_EVENT_LOCALE_CHANGED event (but if you can change the hint, you can + * push your own event, if you want). + * + * The format of this hint is a comma-separated list of language and locale, + * combined with an underscore, as is a common format: "en_GB". Locale is + * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" + +/** + * A variable that decides whether to send SDL_EVENT_QUIT when closing the + * last window. + * + * The variable can be set to the following values: + * + * - "0": SDL will not send an SDL_EVENT_QUIT event when the last window is + * requesting to close. Note that in this case, there are still other + * legitimate reasons one might get an SDL_EVENT_QUIT event: choosing "Quit" + * from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. + * - "1": SDL will send a quit event when the last window is requesting to + * close. (default) + * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" + +/** + * A variable controlling whether the Direct3D device is initialized for + * thread-safe operations. + * + * The variable can be set to the following values: + * + * - "0": Thread-safety is not enabled. (default) + * - "1": Thread-safety is enabled. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" + +/** + * A variable controlling whether to enable Direct3D 11+'s Debug Layer. + * + * This variable does not have any effect on the Direct3D 9 based renderer. + * + * The variable can be set to the following values: + * + * - "0": Disable Debug Layer use. (default) + * - "1": Enable Debug Layer use. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" + +/** + * A variable controlling whether to enable Vulkan Validation Layers. + * + * This variable can be set to the following values: + * + * - "0": Disable Validation Layer use + * - "1": Enable Validation Layer use + * + * By default, SDL does not use Vulkan Validation Layers. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" + +/** + * A variable controlling whether to create the GPU device in debug mode. + * + * This variable can be set to the following values: + * + * - "0": Disable debug mode use (default) + * - "1": Enable debug mode use + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" + +/** + * A variable controlling whether to prefer a low-power GPU on multi-GPU + * systems. + * + * This variable can be set to the following values: + * + * - "0": Prefer high-performance GPU (default) + * - "1": Prefer low-power GPU + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" + +/** + * A variable specifying which render driver to use. + * + * If the application doesn't pick a specific renderer to use, this variable + * specifies the name of the preferred renderer. If the preferred renderer + * can't be initialized, creating a renderer will fail. + * + * This variable is case insensitive and can be set to the following values: + * + * - "direct3d" + * - "direct3d11" + * - "direct3d12" + * - "opengl" + * - "opengles2" + * - "opengles" + * - "metal" + * - "vulkan" + * - "gpu" + * - "software" + * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * + * The default varies by platform, but it's the first one in the list that is + * available on the current platform. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" + +/** + * A variable controlling how the 2D render API renders lines. + * + * The variable can be set to the following values: + * + * - "0": Use the default line drawing method (Bresenham's line algorithm) + * - "1": Use the driver point API using Bresenham's line algorithm (correct, + * draws many points) + * - "2": Use the driver line API (occasionally misses line endpoints based on + * hardware driver quirks + * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" + +/** + * A variable controlling whether the Metal render driver select low power + * device over default one. + * + * The variable can be set to the following values: + * + * - "0": Use the preferred OS device. (default) + * - "1": Select a low power device. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" + +/** + * A variable controlling whether updates to the SDL screen surface should be + * synchronized with the vertical refresh, to avoid tearing. + * + * This hint overrides the application preference when creating a renderer. + * + * The variable can be set to the following values: + * + * - "0": Disable vsync. (default) + * - "1": Enable vsync. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" + +/** + * A variable to control whether the return key on the soft keyboard should + * hide the soft keyboard on Android and iOS. + * + * This hint sets the default value of SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN. + * + * The variable can be set to the following values: + * + * - "0": The return key will be handled as a key event. (default) + * - "1": The return key will hide the keyboard. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" + +/** + * A variable containing a list of ROG gamepad capable mice. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED + */ +#define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" + +/** + * A variable containing a list of devices that are not ROG gamepad capable + * mice. + * + * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" + +/** + * A variable controlling which Dispmanx layer to use on a Raspberry PI. + * + * Also known as Z-order. The variable can take a negative or positive value. + * The default is 10000. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" + +/** + * Specify an "activity name" for screensaver inhibition. + * + * Some platforms, notably Linux desktops, list the applications which are + * inhibiting the screensaver or other power-saving features. + * + * This hint lets you specify the "activity name" sent to the OS when + * SDL_DisableScreenSaver() is used (or the screensaver is automatically + * disabled). The contents of this hint are used when the screensaver is + * disabled. You should use a string that describes what your program is doing + * (and, therefore, why the screensaver is disabled). For example, "Playing a + * game" or "Watching a video". + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "Playing a game" or something similar. + * + * This hint should be set before calling SDL_DisableScreenSaver() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" + +/** + * A variable controlling whether SDL calls dbus_shutdown() on quit. + * + * This is useful as a debug tool to validate memory leaks, but shouldn't ever + * be set in production applications, as other libraries used by the + * application might use dbus under the hood and this can cause crashes if + * they continue after SDL_Quit(). + * + * The variable can be set to the following values: + * + * - "0": SDL will not call dbus_shutdown() on quit. (default) + * - "1": SDL will call dbus_shutdown() on quit. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" + +/** + * A variable that specifies a backend to use for title storage. + * + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for title data. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" + +/** + * A variable that specifies a backend to use for user storage. + * + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for user data. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" + +/** + * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as + * realtime. + * + * On some platforms, like Linux, a realtime priority thread may be subject to + * restrictions that require special handling by the application. This hint + * exists to let SDL know that the app is prepared to handle said + * restrictions. + * + * On Linux, SDL will apply the following configuration to any thread that + * becomes realtime: + * + * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, + * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. + * - Exceeding this limit will result in the kernel sending SIGKILL to the + * app, refer to the man pages for more information. + * + * The variable can be set to the following values: + * + * - "0": default platform specific behaviour + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling + * policy + * + * This hint should be set before calling SDL_SetCurrentThreadPriority() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" + +/** + * A string specifying additional information to use with + * SDL_SetCurrentThreadPriority. + * + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. + * + * pthread hint values are "current", "other", "fifo" and "rr". Currently no + * other platform hint values are defined but may be in the future. + * + * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the + * distro configured execution budget for rtkit. This budget can be queried + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). + * + * This hint should be set before calling SDL_SetCurrentThreadPriority() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" + +/** + * A variable that controls the timer resolution, in milliseconds. + * + * The higher resolution the timer, the more frequently the CPU services timer + * interrupts, and the more precise delays are, but this takes up power and + * CPU time. This hint is only used on Windows. + * + * See this blog post for more information: + * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ + * + * The default value is "1". + * + * If this variable is set to "0", the system timer resolution is not set. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" + +/** + * A variable controlling whether touch events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Touch events will not generate mouse events. + * - "1": Touch events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" + +/** + * A variable controlling whether trackpads should be treated as touch + * devices. + * + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users expect + * from this device; however, these are often actually full multitouch-capable + * touch devices, so it might be preferable to some apps to treat them as + * such. + * + * The variable can be set to the following values: + * + * - "0": Trackpad will send mouse events. (default) + * - "1": Trackpad will send touch events. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" + +/** + * A variable controlling whether the Android / tvOS remotes should be listed + * as joystick devices, instead of sending keyboard events. + * + * The variable can be set to the following values: + * + * - "0": Remotes send enter/escape/arrow key events. + * - "1": Remotes are available as 2 axis, 2 button joysticks. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" + +/** + * A variable controlling whether the screensaver is enabled. + * + * The variable can be set to the following values: + * + * - "0": Disable screensaver. (default) + * - "1": Enable screensaver. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" + +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + +/** + * Tell the video driver that we only want a double buffer. + * + * By default, most lowlevel 2D APIs will use a triple buffer scheme that + * wastes no CPU time on waiting for vsync after issuing a flip, but + * introduces a frame of latency. On the other hand, using a double buffer + * scheme instead is recommended for cases where low latency is an important + * factor because we save a whole frame of latency. + * + * We do so by waiting for vsync immediately after issuing a flip, usually + * just after eglSwapBuffers call in the backend's *_SwapWindow function. + * + * This hint is currently supported on the following drivers: + * + * - Raspberry Pi (raspberrypi) + * - Wayland (wayland) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" + +/** + * A variable that specifies a video backend to use. + * + * By default, SDL will try all available video backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "x11" if, say, you are on Wayland but want + * to try talking to the X server instead. + * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" + +/** + * A variable controlling whether the dummy video driver saves output frames. + * + * - "0": Video frames are not saved to disk. (default) + * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", + * where X is the window ID, and Y is the frame number. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" + +/** + * If eglGetPlatformDisplay fails, fall back to calling eglGetDisplay. + * + * The variable can be set to one of the following values: + * + * - "0": Do not fall back to eglGetDisplay. + * - "1": Fall back to eglGetDisplay if eglGetPlatformDisplay fails. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" + +/** + * A variable controlling whether the OpenGL context should be created with + * EGL. + * + * The variable can be set to the following values: + * + * - "0": Use platform-specific GL context creation API (GLX, WGL, CGL, etc). + * (default) + * - "1": Use EGL + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" + +/** + * A variable that specifies the policy for fullscreen Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and + * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their + * titlebars). + * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and + * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their + * titlebars). (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" + +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + +/** + * A variable controlling whether fullscreen windows are minimized when they + * lose focus. + * + * The variable can be set to the following values: + * + * - "0": Fullscreen windows will not be minimized when they lose focus. + * (default) + * - "1": Fullscreen windows are minimized when they lose focus. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" + +/** + * A variable controlling whether the offscreen video driver saves output + * frames. + * + * This only saves frames that are generated using software rendering, not + * accelerated OpenGL rendering. + * + * - "0": Video frames are not saved to disk. (default) + * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", + * where X is the window ID, and Y is the frame number. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" + +/** + * A variable controlling whether all window operations will block until + * complete. + * + * Window systems that run asynchronously may not have the results of window + * operations that resize or move the window applied immediately upon the + * return of the requesting function. Setting this hint will cause such + * operations to block after every call until the pending operation has + * completed. Setting this to '1' is the equivalent of calling + * SDL_SyncWindow() after every function call. + * + * Be aware that amount of time spent blocking while waiting for window + * operations to complete can be quite lengthy, as animations may have to + * complete, which can take upwards of multiple seconds in some cases. + * + * The variable can be set to the following values: + * + * - "0": Window operations are non-blocking. (default) + * - "1": Window operations will block until completed. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" + +/** + * A variable controlling whether the libdecor Wayland backend is allowed to + * be used. + * + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. + * + * The variable can be set to the following values: + * + * - "0": libdecor use is disabled. + * - "1": libdecor use is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" + +/** + * A variable controlling whether video mode emulation is enabled under + * Wayland. + * + * When this hint is set, a standard set of emulated CVT video modes will be + * exposed for use by the application. If it is disabled, the only modes + * exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. + * + * The variable can be set to the following values: + * + * - "0": Video mode emulation is disabled. + * - "1": Video mode emulation is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" + +/** + * A variable controlling how modes with a non-native aspect ratio are + * displayed under Wayland. + * + * When this hint is set, the requested scaling will be used when displaying + * fullscreen video modes that don't match the display's native aspect ratio. + * This is contingent on compositor viewport support. + * + * The variable can be set to the following values: + * + * - "aspect" - Video modes will be displayed scaled, in their proper aspect + * ratio, with black bars. + * - "stretch" - Video modes will be scaled to fill the entire display. + * (default) + * - "none" - Video modes will be displayed as 1:1 with no scaling. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" + +/** + * A variable controlling whether the libdecor Wayland backend is preferred + * over native decorations. + * + * When this hint is set, libdecor will be used to provide window decorations, + * even if xdg-decoration is available. (Note that, by default, libdecor will + * use xdg-decoration itself if available). + * + * The variable can be set to the following values: + * + * - "0": libdecor is enabled only if server-side decorations are unavailable. + * (default) + * - "1": libdecor is always enabled if available. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" + +/** + * A variable forcing non-DPI-aware Wayland windows to output at 1:1 scaling. + * + * This must be set before initializing the video subsystem. + * + * When this hint is set, Wayland windows that are not flagged as being + * DPI-aware will be output with scaling designed to force 1:1 pixel mapping. + * + * This is intended to allow legacy applications to be displayed without + * desktop scaling being applied, and has issues with certain display + * configurations, as this forces the window to behave in a way that Wayland + * desktops were not designed to accommodate: + * + * - Rounding errors can result with odd window sizes and/or desktop scales, + * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. + * - The window may be unusably small on scaled desktops. + * - The window may jump in size when moving between displays of different + * scale factors. + * - Displays may appear to overlap when using a multi-monitor setup with + * scaling enabled. + * - Possible loss of cursor precision due to the logical size of the window + * being reduced. + * + * New applications should be designed with proper DPI awareness handling + * instead of enabling this. + * + * The variable can be set to the following values: + * + * - "0": Windows will be scaled normally. + * - "1": Windows will be forced to scale to achieve 1:1 output. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" + +/** + * A variable specifying which shader compiler to preload when using the + * Chrome ANGLE binaries. + * + * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can + * use two different sets of binaries, those compiled by the user from source + * or those provided by the Chrome browser. In the later case, these binaries + * require that SDL loads a DLL providing the shader compiler. + * + * The variable can be set to the following values: + * + * - "d3dcompiler_46.dll" - best for Vista or later. (default) + * - "d3dcompiler_43.dll" - for XP support. + * - "none" - do not load any library, useful if you compiled ANGLE from + * source and included the compiler in your binaries. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" + +/** + * A variable controlling whether SDL should call XSelectInput() to enable + * input events on X11 windows wrapped by SDL windows. + * + * The variable can be set to the following values: + * + * - "0": Don't call XSelectInput(), assuming the native window code has done + * it already. + * - "1": Call XSelectInput() to enable input events. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.10. + */ +#define SDL_HINT_VIDEO_X11_EXTERNAL_WINDOW_INPUT "SDL_VIDEO_X11_EXTERNAL_WINDOW_INPUT" + +/** + * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint + * should be used. + * + * The variable can be set to the following values: + * + * - "0": Disable _NET_WM_BYPASS_COMPOSITOR. + * - "1": Enable _NET_WM_BYPASS_COMPOSITOR. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" + +/** + * A variable controlling whether the X11 _NET_WM_PING protocol should be + * supported. + * + * By default SDL will use _NET_WM_PING, but for applications that know they + * will not always be able to respond to ping requests in a timely manner they + * can turn it off to avoid the window manager thinking the app is hung. + * + * The variable can be set to the following values: + * + * - "0": Disable _NET_WM_PING. + * - "1": Enable _NET_WM_PING. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" + +/** + * A variable controlling whether SDL uses DirectColor visuals. + * + * The variable can be set to the following values: + * + * - "0": Disable DirectColor visuals. + * - "1": Enable DirectColor visuals. (default) + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" + +/** + * A variable forcing the content scaling factor for X11 displays. + * + * The variable can be set to a floating point value in the range 1.0-10.0f + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" + +/** + * A variable forcing the visual ID used for X11 display modes. + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" + +/** + * A variable forcing the visual ID chosen for new X11 windows. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" + +/** + * A variable controlling whether the X11 XRandR extension should be used. + * + * The variable can be set to the following values: + * + * - "0": Disable XRandR. + * - "1": Enable XRandR. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" + +/** + * A variable controlling whether touch should be enabled on the back panel of + * the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Disable touch on the back panel. + * - "1": Enable touch on the back panel. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" + +/** + * A variable controlling whether touch should be enabled on the front panel + * of the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Disable touch on the front panel. + * - "1": Enable touch on the front panel. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" + +/** + * A variable controlling the module path on the PlayStation Vita. + * + * This hint defaults to "app0:module" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" + +/** + * A variable controlling whether to perform PVR initialization on the + * PlayStation Vita. + * + * - "0": Skip PVR initialization. + * - "1": Perform the normal PVR initialization. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" + +/** + * A variable overriding the resolution reported on the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "544": 544p (default) + * - "720": 725p for PSTV + * - "1080": 1088i for PSTV + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" + +/** + * A variable controlling whether OpenGL should be used instead of OpenGL ES + * on the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Use OpenGL ES. (default) + * - "1": Use OpenGL. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" + +/** + * A variable controlling which touchpad should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Only front touchpad should generate mouse events. (default) + * - "1": Only back touchpad should generate mouse events. + * - "2": Both touchpads should generate mouse events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" + +/** + * A variable overriding the display index used in SDL_Vulkan_CreateSurface() + * + * The display index starts at 0, which is the default. + * + * This hint should be set before calling SDL_Vulkan_CreateSurface() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" + +/** + * Specify the Vulkan library to load. + * + * This hint should be set before creating a Vulkan window or calling + * SDL_Vulkan_LoadLibrary(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" + +/** + * A variable controlling how the fact chunk affects the loading of a WAVE + * file. + * + * The fact chunk stores information about the number of samples of a WAVE + * file. The Standards Update from Microsoft notes that this value can be used + * to 'determine the length of the data in seconds'. This is especially useful + * for compressed formats (for which this is a mandatory chunk) if they + * produce multiple sample frames per block and truncating the block is not + * allowed. The fact chunk can exactly specify how many sample frames there + * should be in this case. + * + * Unfortunately, most application seem to ignore the fact chunk and so SDL + * ignores it by default as well. + * + * The variable can be set to the following values: + * + * - "truncate" - Use the number of samples to truncate the wave data if the + * fact chunk is present and valid. + * - "strict" - Like "truncate", but raise an error if the fact chunk is + * invalid, not present for non-PCM formats, or if the data chunk doesn't + * have that many samples. + * - "ignorezero" - Like "truncate", but ignore fact chunk if the number of + * samples is zero. + * - "ignore" - Ignore fact chunk entirely. (default) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" + +/** + * A variable controlling the maximum number of chunks in a WAVE file. + * + * This sets an upper bound on the number of chunks in a WAVE file to avoid + * wasting time on malformed or corrupt WAVE files. This defaults to "10000". + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" + +/** + * A variable controlling how the size of the RIFF chunk affects the loading + * of a WAVE file. + * + * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE + * file) is not always reliable. In case the size is wrong, it's possible to + * just ignore it and step through the chunks until a fixed limit is reached. + * + * Note that files that have trailing data unrelated to the WAVE file or + * corrupt files may slow down the loading process without a reliable + * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. + * Use SDL_HINT_WAVE_CHUNK_LIMIT to adjust this value. + * + * The variable can be set to the following values: + * + * - "force" - Always use the RIFF chunk size as a boundary for the chunk + * search. + * - "ignorezero" - Like "force", but a zero size searches up to 4 GiB. + * (default) + * - "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB. + * - "maximum" - Search for chunks until the end of file. (not recommended) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" + +/** + * A variable controlling how a truncated WAVE file is handled. + * + * A WAVE file is considered truncated if any of the chunks are incomplete or + * the data chunk size is not a multiple of the block size. By default, SDL + * decodes until the first incomplete block, as most applications seem to do. + * + * The variable can be set to the following values: + * + * - "verystrict" - Raise an error if the file is truncated. + * - "strict" - Like "verystrict", but the size of the RIFF chunk is ignored. + * - "dropframe" - Decode until the first incomplete sample frame. + * - "dropblock" - Decode until the first incomplete block. (default) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" + +/** + * A variable controlling whether the window is activated when the + * SDL_RaiseWindow function is called. + * + * The variable can be set to the following values: + * + * - "0": The window is not activated when the SDL_RaiseWindow function is + * called. + * - "1": The window is activated when the SDL_RaiseWindow function is called. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" + +/** + * A variable controlling whether the window is activated when the + * SDL_ShowWindow function is called. + * + * The variable can be set to the following values: + * + * - "0": The window is not activated when the SDL_ShowWindow function is + * called. + * - "1": The window is activated when the SDL_ShowWindow function is called. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" + +/** + * If set to "0" then never set the top-most flag on an SDL Window even if the + * application requests it. + * + * This is a debugging aid for developers and not expected to be used by end + * users. + * + * The variable can be set to the following values: + * + * - "0": don't allow topmost + * - "1": allow topmost (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" + +/** + * A variable controlling whether the window frame and title bar are + * interactive when the cursor is hidden. + * + * The variable can be set to the following values: + * + * - "0": The window frame is not interactive when the cursor is hidden (no + * move, resize, etc). + * - "1": The window frame is interactive when the cursor is hidden. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" + +/** + * A variable controlling whether SDL generates window-close events for Alt+F4 + * on Windows. + * + * The variable can be set to the following values: + * + * - "0": SDL will only do normal key handling for Alt+F4. + * - "1": SDL will generate a window-close event when it sees Alt+F4. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" + +/** + * A variable controlling whether menus can be opened with their keyboard + * shortcut (Alt+mnemonic). + * + * If the mnemonics are enabled, then menus can be opened by pressing the Alt + * key and the corresponding mnemonic (for example, Alt+F opens the File + * menu). However, in case an invalid mnemonic is pressed, Windows makes an + * audible beep to convey that nothing happened. This is true even if the + * window has no menu at all! + * + * Because most SDL applications don't have menus, and some want to use the + * Alt key for other purposes, SDL disables mnemonics (and the beeping) by + * default. + * + * Note: This also affects keyboard events: with mnemonics enabled, when a + * menu is opened from the keyboard, you will not receive a KEYUP event for + * the mnemonic key, and *might* not receive one for Alt. + * + * The variable can be set to the following values: + * + * - "0": Alt+mnemonic does nothing, no beeping. (default) + * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" + +/** + * A variable controlling whether the windows message loop is processed by + * SDL. + * + * The variable can be set to the following values: + * + * - "0": The window message loop is not run. + * - "1": The window message loop is processed in SDL_PumpEvents(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" + +/** + * A variable controlling whether GameInput is used for raw keyboard and mouse + * on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used for raw keyboard and mouse events. + * - "1": GameInput is used for raw keyboard and mouse events, if available. + * (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" + +/** + * A variable controlling whether raw keyboard events are used on Windows. + * + * The variable can be set to the following values: + * + * - "0": The Windows message loop is used for keyboard events. (default) + * - "1": Low latency raw keyboard events are used. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" + +/** + * A variable controlling whether SDL uses Kernel Semaphores on Windows. + * + * Kernel Semaphores are inter-process and require a context switch on every + * interaction. On Windows 8 and newer, the WaitOnAddress API is available. + * Using that and atomics to implement semaphores increases performance. SDL + * will fall back to Kernel Objects on older OS versions or if forced to by + * this hint. + * + * The variable can be set to the following values: + * + * - "0": Use Atomics and WaitOnAddress API when available, otherwise fall + * back to Kernel Objects. (default) + * - "1": Force the use of Kernel Objects in all cases. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" + +/** + * 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.2.0. + */ +#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.2.0. + */ +#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" + +/** + * A variable controlling whether SDL uses the D3D9Ex API introduced in + * Windows Vista, instead of normal D3D9. + * + * Direct3D 9Ex contains changes to state management that can eliminate device + * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may + * require some changes to your application to cope with the new behavior, so + * this is disabled by default. + * + * For more information on Direct3D 9Ex, see: + * + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements + * + * The variable can be set to the following values: + * + * - "0": Use the original Direct3D 9 API. (default) + * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex + * is unavailable) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" + +/** + * A variable controlling whether SDL will clear the window contents when the + * WM_ERASEBKGND message is received. + * + * The variable can be set to the following values: + * + * - "0"/"never": Never clear the window. + * - "1"/"initial": Clear the window when the first WM_ERASEBKGND event fires. + * (default) + * - "2"/"always": Clear the window on every WM_ERASEBKGND event. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" + +/** + * A variable controlling whether X11 windows are marked as override-redirect. + * + * If set, this _might_ increase framerate at the expense of the desktop not + * working as expected. Override-redirect windows aren't noticed by the window + * manager at all. + * + * You should probably only use this for fullscreen windows, and you probably + * shouldn't even use it for that. But it's here if you want to try! + * + * The variable can be set to the following values: + * + * - "0": Do not mark the window as override-redirect. (default) + * - "1": Mark the window as override-redirect. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" + +/** + * A variable specifying the type of an X11 window. + * + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to + * report to the window manager the type of window it wants to create. This + * might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" + +/** + * Specify the XCB library to load for the X11 driver. + * + * The default is platform-specific, often "libX11-xcb.so.1". + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" + +/** + * A variable controlling whether XInput should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": XInput is not enabled. + * - "1": XInput is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" + +/** + * A variable controlling response to SDL_assert failures. + * + * The variable can be set to the following case-sensitive values: + * + * - "abort": Program terminates immediately. + * - "break": Program triggers a debugger breakpoint. + * - "retry": Program reruns the SDL_assert's test again. + * - "ignore": Program continues on, ignoring this assertion failure this + * time. + * - "always_ignore": Program continues on, ignoring this assertion failure + * for the rest of the run. + * + * Note that SDL_SetAssertionHandler offers a programmatic means to deal with + * assertion failures through a callback, and this hint is largely intended to + * be used via environment variables by end users and automated tools. + * + * This hint should be set before an assertion failure is triggered and can be + * changed at any time. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ASSERT "SDL_ASSERT" + +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + + +/** + * An enumeration of hint priorities. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_HintPriority +{ + SDL_HINT_DEFAULT, + SDL_HINT_NORMAL, + SDL_HINT_OVERRIDE +} SDL_HintPriority; + +/** + * Set a hint with a specific priority. + * + * The priority controls the behavior when setting a hint that already has a + * value. Hints will replace existing hints of their priority and lower. + * Environment variables are considered to have override priority. + * + * \param name the hint to set. + * \param value the value of the hint variable. + * \param priority the SDL_HintPriority level for the hint. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_ResetHint + * \sa SDL_SetHint + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); + +/** + * Set a hint with normal priority. + * + * Hints will not be set if there is an existing override hint or environment + * variable that takes precedence. You can use SDL_SetHintWithPriority() to + * set the hint with override priority instead. + * + * \param name the hint to set. + * \param value the value of the hint variable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_ResetHint + * \sa SDL_SetHintWithPriority + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); + +/** + * Reset a hint to the default value. + * + * This will reset a hint to the value of the environment variable, or NULL if + * the environment isn't set. Callbacks will be called normally with this + * change. + * + * \param name the hint to set. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetHint + * \sa SDL_ResetHints + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); + +/** + * Reset all hints to the default values. + * + * This will reset all hints to the value of the associated environment + * variable, or NULL if the environment isn't set. Callbacks will be called + * normally with this change. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResetHint + */ +extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); + +/** + * Get the value of a hint. + * + * \param name the hint to query. + * \returns the string value of a hint or NULL if the hint isn't set. + * + * \threadsafety It is safe to call this function from any thread, however the + * return value only remains valid until the hint is changed; if + * another thread might do so, the app should supply locks + * and/or make a copy of the string. Note that using a hint + * callback instead is always thread-safe, as SDL holds a lock + * on the thread subsystem during the callback. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetHint + * \sa SDL_SetHintWithPriority + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); + +/** + * Get the boolean value of a hint variable. + * + * \param name the name of the hint to get the boolean value from. + * \param default_value the value to return if the hint does not exist. + * \returns the boolean value of a hint or the provided default value if the + * hint does not exist. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_SetHint + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); + +/** + * A callback used to send notifications of hint value changes. + * + * This is called an initial time during SDL_AddHintCallback with the hint's + * current value, and then again each time the hint's value changes. + * + * \param userdata what was passed as `userdata` to SDL_AddHintCallback(). + * \param name what was passed as `name` to SDL_AddHintCallback(). + * \param oldValue the previous hint value. + * \param newValue the new value hint is to be set to. + * + * \threadsafety This callback is fired from whatever thread is setting a new + * hint value. SDL holds a lock on the hint subsystem when + * calling this callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_AddHintCallback + */ +typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); + +/** + * Add a function to watch a particular hint. + * + * The callback function is called _during_ this function, to provide it an + * initial value, and again each time the hint's value changes. + * + * \param name the hint to watch. + * \param callback An SDL_HintCallback function that will be called when the + * hint value changes. + * \param userdata a pointer to pass to the callback function. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveHintCallback + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); + +/** + * Remove a function watching a particular hint. + * + * \param name the hint being watched. + * \param callback an SDL_HintCallback function that will be called when the + * hint value changes. + * \param userdata a pointer being passed to the callback function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddHintCallback + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveHintCallback(const char *name, + SDL_HintCallback callback, + void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_hints_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_init.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_init.h new file mode 100644 index 0000000000..27ebe4b0ed --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_init.h @@ -0,0 +1,497 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryInit + * + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). + */ + +#ifndef SDL_init_h_ +#define SDL_init_h_ + +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* As of version 0.5, SDL is loaded dynamically into the application */ + +/** + * Initialization flags for SDL_Init and/or SDL_InitSubSystem + * + * These are the flags which may be passed to SDL_Init(). You should specify + * the subsystems which you will be using in your application. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_Quit + * \sa SDL_InitSubSystem + * \sa SDL_QuitSubSystem + * \sa SDL_WasInit + */ +typedef Uint32 SDL_InitFlags; + +#define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ +#define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_HAPTIC 0x00001000u +#define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ +#define SDL_INIT_EVENTS 0x00004000u +#define SDL_INIT_SENSOR 0x00008000u /**< `SDL_INIT_SENSOR` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_CAMERA 0x00010000u /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */ + +/** + * Return values for optional main callbacks. + * + * Returning SDL_APP_SUCCESS or SDL_APP_FAILURE from SDL_AppInit, + * SDL_AppEvent, or SDL_AppIterate will terminate the program and report + * success/failure to the operating system. What that means is + * platform-dependent. On Unix, for example, on success, the process error + * code will be zero, and on failure it will be 1. This interface doesn't + * allow you to return specific exit codes, just whether there was an error + * generally or not. + * + * Returning SDL_APP_CONTINUE from these functions will let the app continue + * to run. + * + * See + * [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3) + * for complete details. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AppResult +{ + SDL_APP_CONTINUE, /**< Value that requests that the app continue from the main callbacks. */ + SDL_APP_SUCCESS, /**< Value that requests termination with success from the main callbacks. */ + 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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + + +/** + * Initialize the SDL library. + * + * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the + * two may be used interchangeably. Though for readability of your code + * SDL_InitSubSystem() might be preferred. + * + * The file I/O (for example: SDL_IOFromFile) and threading (SDL_CreateThread) + * subsystems are initialized by default. Message boxes + * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the + * video subsystem, in hopes of being useful in showing an error dialog when + * SDL_Init fails. You must specifically initialize other subsystems if you + * use them in your application. + * + * Logging (such as SDL_Log) works without initialization, too. + * + * `flags` may be any of the following OR'd together: + * + * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events + * subsystem + * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events + * subsystem, should be initialized on the main thread. + * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the + * events subsystem + * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem + * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically initializes the + * joystick subsystem + * - `SDL_INIT_EVENTS`: events subsystem + * - `SDL_INIT_SENSOR`: sensor subsystem; automatically initializes the events + * subsystem + * - `SDL_INIT_CAMERA`: camera subsystem; automatically initializes the events + * subsystem + * + * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem() + * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or + * call SDL_Quit() to force shutdown). If a subsystem is already loaded then + * this call will increase the ref-count and return. + * + * Consider reporting some basic metadata about your application before + * calling SDL_Init, using either SDL_SetAppMetadata() or + * SDL_SetAppMetadataProperty(). + * + * \param flags subsystem initialization flags. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAppMetadata + * \sa SDL_SetAppMetadataProperty + * \sa SDL_InitSubSystem + * \sa SDL_Quit + * \sa SDL_SetMainReady + * \sa SDL_WasInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); + +/** + * Compatibility function to initialize the SDL library. + * + * This function and SDL_Init() are interchangeable. + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_Quit + * \sa SDL_QuitSubSystem + */ +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); + +/** + * Shut down specific SDL subsystems. + * + * You still need to call SDL_Quit() even if you close all open subsystems + * with SDL_QuitSubSystem(). + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InitSubSystem + * \sa SDL_Quit + */ +extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); + +/** + * Get a mask of the specified subsystems which are currently initialized. + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it + * returns the initialization status of the specified subsystems. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_InitSubSystem + */ +extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); + +/** + * Clean up all initialized subsystems. + * + * You should call this function even if you have already shutdown each + * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this + * function even in the case of errors in initialization. + * + * You can use this function with atexit() to ensure that it is run when your + * application is shutdown, but it is not wise to do this from a library or + * other dynamically loaded code. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_QuitSubSystem + */ +extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); + +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + +/** + * Specify basic metadata about your app. + * + * You can optionally provide metadata about your app to SDL. This is not + * required, but strongly encouraged. + * + * There are several locations where SDL can make use of metadata (an "About" + * box in the macOS menu bar, the name of the app can be shown on some audio + * mixers, etc). Any piece of metadata can be left as NULL, if a specific + * detail doesn't make sense for the app. + * + * This function should be called as early as possible, before SDL_Init. + * Multiple calls to this function are allowed, but various state might not + * change once it has been set up with a previous call to this function. + * + * Passing a NULL removes any previous metadata. + * + * This is a simplified interface for the most important information. You can + * supply significantly more detailed metadata with + * SDL_SetAppMetadataProperty(). + * + * \param appname The name of the application ("My Game 2: Bad Guy's + * Revenge!"). + * \param appversion The version of the application ("1.0.0beta5" or a git + * hash, or whatever makes sense). + * \param appidentifier A unique string in reverse-domain format that + * identifies this app ("com.example.mygame2"). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAppMetadataProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); + +/** + * Specify metadata about your app through a set of properties. + * + * You can optionally provide metadata about your app to SDL. This is not + * required, but strongly encouraged. + * + * There are several locations where SDL can make use of metadata (an "About" + * box in the macOS menu bar, the name of the app can be shown on some audio + * mixers, etc). Any piece of metadata can be left out, if a specific detail + * doesn't make sense for the app. + * + * This function should be called as early as possible, before SDL_Init. + * Multiple calls to this function are allowed, but various state might not + * change once it has been set up with a previous call to this function. + * + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). + * + * These are the supported properties: + * + * - `SDL_PROP_APP_METADATA_NAME_STRING`: The human-readable name of the + * application, like "My Game 2: Bad Guy's Revenge!". This will show up + * anywhere the OS shows the name of the application separately from window + * titles, such as volume control applets, etc. This defaults to "SDL + * Application". + * - `SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that is + * running; there are no rules on format, so "1.0.3beta2" and "April 22nd, + * 2024" and a git hash are all valid options. This has no default. + * - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that + * identifies this app. This must be in reverse-domain format, like + * "com.example.mygame2". This string is used by desktop compositors to + * identify and group windows together, as well as match applications with + * associated desktop settings and icons. If you plan to package your + * application in a container such as Flatpak, the app ID should match the + * name of your Flatpak container as well. This has no default. + * - `SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name of the + * creator/developer/maker of this app, like "MojoWorkshop, LLC" + * - `SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright + * notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this + * to one line, don't paste a copy of a whole software license in here. This + * has no default. + * - `SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe a + * product page, or a storefront, or even a GitHub repository, for user's + * further information This has no default. + * - `SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is. + * Currently this string can be "game" for a video game, "mediaplayer" for a + * media player, or generically "application" if nothing else applies. + * Future versions of SDL might add new types. This defaults to + * "application". + * + * \param name the name of the metadata property to set. + * \param value the value of the property, or NULL to remove that property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAppMetadataProperty + * \sa SDL_SetAppMetadata + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); + +#define SDL_PROP_APP_METADATA_NAME_STRING "SDL.app.metadata.name" +#define SDL_PROP_APP_METADATA_VERSION_STRING "SDL.app.metadata.version" +#define SDL_PROP_APP_METADATA_IDENTIFIER_STRING "SDL.app.metadata.identifier" +#define SDL_PROP_APP_METADATA_CREATOR_STRING "SDL.app.metadata.creator" +#define SDL_PROP_APP_METADATA_COPYRIGHT_STRING "SDL.app.metadata.copyright" +#define SDL_PROP_APP_METADATA_URL_STRING "SDL.app.metadata.url" +#define SDL_PROP_APP_METADATA_TYPE_STRING "SDL.app.metadata.type" + +/** + * Get metadata about your app. + * + * This returns metadata previously set using SDL_SetAppMetadata() or + * SDL_SetAppMetadataProperty(). See SDL_SetAppMetadataProperty() for the list + * of available properties and their meanings. + * + * \param name the name of the metadata property to get. + * \returns the current value of the metadata property, or the default if it + * is not set, NULL for properties with no default. + * + * \threadsafety It is safe to call this function from any thread, although + * the string returned is not protected and could potentially be + * freed if you call SDL_SetAppMetadataProperty() to set that + * property from another thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAppMetadata + * \sa SDL_SetAppMetadataProperty + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAppMetadataProperty(const char *name); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_init_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_intrin.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_intrin.h new file mode 100644 index 0000000000..bac6d7ad4f --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_intrin.h @@ -0,0 +1,407 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. + */ + +#ifndef SDL_intrin_h_ +#define SDL_intrin_h_ + +#include + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + +/* Need to do this here because intrin.h has C++ code in it */ +/* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ +#if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) +#ifdef __clang__ +/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version, + so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */ +#ifndef __PRFCHWINTRIN_H +#define __PRFCHWINTRIN_H +static __inline__ void __attribute__((__always_inline__, __nodebug__)) +_m_prefetch(void *__P) +{ + __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */); +} +#endif /* __PRFCHWINTRIN_H */ +#endif /* __clang__ */ +#include + +#elif defined(__MINGW64_VERSION_MAJOR) +#include +#if defined(__ARM_NEON) && !defined(SDL_DISABLE_NEON) +# define SDL_NEON_INTRINSICS 1 +# include +#endif + +#else +/* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC to have it included. */ +#if defined(__ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC) +#define SDL_ALTIVEC_INTRINSICS 1 +#include +#endif +#ifndef SDL_DISABLE_NEON +# ifdef __ARM_NEON +# define SDL_NEON_INTRINSICS 1 +# include +# elif defined(SDL_PLATFORM_WINDOWS) +/* Visual Studio doesn't define __ARM_ARCH, but _M_ARM (if set, always 7), and _M_ARM64 (if set, always 1). */ +# ifdef _M_ARM +# define SDL_NEON_INTRINSICS 1 +# include +# include +# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */ +# endif +# if defined (_M_ARM64) +# define SDL_NEON_INTRINSICS 1 +# include +# include +# define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */ +# define __ARM_ARCH 8 +# endif +# endif +#endif +#endif /* compiler version */ + +#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.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) +# if __has_attribute(target) +# define SDL_HAS_TARGET_ATTRIBS +# endif +#elif defined(__GNUC__) && (__GNUC__ + (__GNUC_MINOR__ >= 9) > 4) /* gcc >= 4.9 */ +# define SDL_HAS_TARGET_ATTRIBS +#elif defined(__ICC) && __ICC >= 1600 +# define SDL_HAS_TARGET_ATTRIBS +#endif + + +#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.2.0. + */ +#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) +#endif + +#ifdef __loongarch64 +# ifndef SDL_DISABLE_LSX +# define SDL_LSX_INTRINSICS 1 +# include +# endif +# ifndef SDL_DISABLE_LASX +# define SDL_LASX_INTRINSICS 1 +# include +# endif +#endif + +#if defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86) +# if ((defined(_MSC_VER) && !defined(_M_X64)) || defined(__MMX__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_MMX) +# define SDL_MMX_INTRINSICS 1 +# include +# endif +# if (defined(_MSC_VER) || defined(__SSE__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_SSE) +# define SDL_SSE_INTRINSICS 1 +# include +# endif +# if (defined(_MSC_VER) || defined(__SSE2__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_SSE2) +# define SDL_SSE2_INTRINSICS 1 +# include +# endif +# if (defined(_MSC_VER) || defined(__SSE3__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_SSE3) +# define SDL_SSE3_INTRINSICS 1 +# include +# endif +# if (defined(_MSC_VER) || defined(__SSE4_1__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_SSE4_1) +# define SDL_SSE4_1_INTRINSICS 1 +# include +# endif +# if (defined(_MSC_VER) || defined(__SSE4_2__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(SDL_DISABLE_SSE4_2) +# define SDL_SSE4_2_INTRINSICS 1 +# include +# endif +# if defined(__clang__) && (defined(_MSC_VER) || defined(__SCE__)) && !defined(__AVX__) && !defined(SDL_DISABLE_AVX) +# define SDL_DISABLE_AVX /* see https://reviews.llvm.org/D20291 and https://reviews.llvm.org/D79194 */ +# endif +# if (defined(_MSC_VER) || defined(__AVX__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(_M_ARM64EC) && !defined(SDL_DISABLE_AVX) +# define SDL_AVX_INTRINSICS 1 +# include +# endif +# if defined(__clang__) && (defined(_MSC_VER) || defined(__SCE__)) && !defined(__AVX2__) && !defined(SDL_DISABLE_AVX2) +# define SDL_DISABLE_AVX2 /* see https://reviews.llvm.org/D20291 and https://reviews.llvm.org/D79194 */ +# endif +# if (defined(_MSC_VER) || defined(__AVX2__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(_M_ARM64EC) && !defined(SDL_DISABLE_AVX2) +# define SDL_AVX2_INTRINSICS 1 +# include +# endif +# if defined(__clang__) && (defined(_MSC_VER) || defined(__SCE__)) && !defined(__AVX512F__) && !defined(SDL_DISABLE_AVX512F) +# define SDL_DISABLE_AVX512F /* see https://reviews.llvm.org/D20291 and https://reviews.llvm.org/D79194 */ +# endif +# if (defined(_MSC_VER) || defined(__AVX512F__) || defined(SDL_HAS_TARGET_ATTRIBS)) && !defined(_M_ARM64EC) && !defined(SDL_DISABLE_AVX512F) +# define SDL_AVX512F_INTRINSICS 1 +# include +# endif +#endif /* defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86) */ + +#endif /* SDL_intrin_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_iostream.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_iostream.h new file mode 100644 index 0000000000..4ca16093e5 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_iostream.h @@ -0,0 +1,1354 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: IOStream */ + +/** + * # CategoryIOStream + * + * SDL provides an abstract interface for reading and writing data streams. It + * offers implementations for files, memory, etc, and the app can provide + * their own implementations, too. + * + * SDL_IOStream is not related to the standard C++ iostream class, other than + * both are abstract interfaces to read/write data. + */ + +#ifndef SDL_iostream_h_ +#define SDL_iostream_h_ + +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * SDL_IOStream status, set by a read or write operation. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_IOStatus +{ + SDL_IO_STATUS_READY, /**< Everything is ready (no errors and not EOF). */ + SDL_IO_STATUS_ERROR, /**< Read or write I/O error */ + SDL_IO_STATUS_EOF, /**< End of file */ + SDL_IO_STATUS_NOT_READY, /**< Non blocking I/O, not ready */ + SDL_IO_STATUS_READONLY, /**< Tried to write a read-only buffer */ + SDL_IO_STATUS_WRITEONLY /**< Tried to read a write-only buffer */ +} SDL_IOStatus; + +/** + * Possible `whence` values for SDL_IOStream seeking. + * + * These map to the same "whence" concept that `fseek` or `lseek` use in the + * standard C runtime. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_IOWhence +{ + SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ + SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ +} SDL_IOWhence; + +/** + * The function pointers that drive an SDL_IOStream. + * + * Applications can provide this struct to SDL_OpenIO() to create their own + * implementation of SDL_IOStream. This is not necessarily required, as SDL + * already offers several common types of I/O streams, via functions like + * SDL_IOFromFile() and SDL_IOFromMem(). + * + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE + */ +typedef struct SDL_IOStreamInterface +{ + /* The version of this interface */ + Uint32 version; + + /** + * Return the number of bytes in this SDL_IOStream + * + * \return the total size of the data stream, or -1 on error. + */ + Sint64 (SDLCALL *size)(void *userdata); + + /** + * Seek to `offset` relative to `whence`, one of stdio's whence values: + * SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END + * + * \return the final offset in the data stream, or -1 on error. + */ + Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence); + + /** + * Read up to `size` bytes from the data stream to the area pointed + * at by `ptr`. + * + * On an incomplete read, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a complete, successful read. + * + * \return the number of bytes read + */ + size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status); + + /** + * Write exactly `size` bytes from the area pointed at by `ptr` + * to data stream. + * + * On an incomplete write, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a complete, successful write. + * + * \return the number of bytes written + */ + size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + + /** + * Close and free any allocated resources. + * + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. + * + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *close)(void *userdata); + +} SDL_IOStreamInterface; + +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); + +/** + * The read/write operation structure. + * + * This operates as an opaque handle. There are several APIs to create various + * types of I/O streams, or an app can supply an SDL_IOStreamInterface to + * SDL_OpenIO() to provide their own stream implementation behind this + * struct's abstract interface. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_IOStream SDL_IOStream; + + +/** + * \name IOFrom functions + * + * Functions to create SDL_IOStream structures from various data streams. + */ +/* @{ */ + +/** + * Use this function to create a new SDL_IOStream structure for reading from + * and/or writing to a named file. + * + * The `mode` string is treated roughly the same as in a call to the C + * library's fopen(), even if SDL doesn't happen to use fopen() behind the + * scenes. + * + * Available `mode` strings: + * + * - "r": Open a file for reading. The file must exist. + * - "w": Create an empty file for writing. If a file with the same name + * already exists its content is erased and the file is treated as a new + * empty file. + * - "a": Append to a file. Writing operations append data at the end of the + * file. The file is created if it does not exist. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * - "a+": Open a file for reading and appending. All writing operations are + * performed at the end of the file, protecting the previous content to be + * overwritten. You can reposition (fseek, rewind) the internal pointer to + * anywhere in the file for reading, but writing operations will move it + * back to the end of file. The file is created if it does not exist. + * + * **NOTE**: In order to open a file as a binary file, a "b" character has to + * be included in the `mode` string. This additional "b" character can either + * be appended at the end of the string (thus making the following compound + * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the + * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). + * Additional characters may follow the sequence, although they should have no + * effect. For example, "t" is sometimes appended to make explicit the file is + * a text file. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * In Android, SDL_IOFromFile() can be used to open content:// URIs. As a + * fallback, SDL_IOFromFile() will transparently open a matching filename in + * the app's `assets`. + * + * Closing the SDL_IOStream will close SDL's internal file handle. + * + * The following properties may be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`: a pointer, that can be cast + * to a win32 `HANDLE`, that this SDL_IOStream is using to access the + * filesystem. If the program isn't running on Windows, or SDL used some + * other method to access the filesystem, this property will not be set. + * - `SDL_PROP_IOSTREAM_STDIO_FILE_POINTER`: a pointer, that can be cast to a + * stdio `FILE *`, that this SDL_IOStream is using to access the filesystem. + * If SDL used some other method to access the filesystem, this property + * will not be set. PLEASE NOTE that if SDL is using a different C runtime + * than your app, trying to use this pointer will almost certainly result in + * a crash! This is mostly a problem on Windows; make sure you build SDL and + * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. + * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast + * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access + * the filesystem. If SDL used some other method to access the filesystem, + * this property will not be set. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_IOStream structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_FlushIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, const char *mode); + +#define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" +#define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" +#define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" + +/** + * Use this function to prepare a read-write memory buffer for use with + * SDL_IOStream. + * + * This function sets up an SDL_IOStream struct based on a memory area of a + * certain size, for both read and write access. + * + * This memory buffer is not copied by the SDL_IOStream; the pointer you + * provide must remain valid until you close the stream. Closing the stream + * will not free the original buffer. + * + * If you need to make sure the SDL_IOStream never writes to the memory + * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of + * memory instead. + * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * + * \param mem a pointer to a buffer to feed an SDL_IOStream stream. + * \param size the buffer size, in bytes. + * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOFromConstMem + * \sa SDL_CloseIO + * \sa SDL_FlushIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); + +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + +/** + * Use this function to prepare a read-only memory buffer for use with + * SDL_IOStream. + * + * This function sets up an SDL_IOStream struct based on a memory area of a + * certain size. It assumes the memory area is not writable. + * + * Attempting to write to this SDL_IOStream stream will report an error + * without writing to the memory buffer. + * + * This memory buffer is not copied by the SDL_IOStream; the pointer you + * provide must remain valid until you close the stream. Closing the stream + * will not free the original buffer. + * + * If you need to write to a memory buffer, you should use SDL_IOFromMem() + * with a writable buffer of memory instead. + * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * + * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. + * \param size the buffer size, in bytes. + * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOFromMem + * \sa SDL_CloseIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, size_t size); + +/** + * Use this function to create an SDL_IOStream that is backed by dynamically + * allocated memory. + * + * This supports the following properties to provide access to the memory and + * control over allocations: + * + * - `SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER`: a pointer to the internal + * memory of the stream. This can be set to NULL to transfer ownership of + * the memory to the application, which should free the memory with + * SDL_free(). If this is done, the next operation on the stream must be + * SDL_CloseIO(). + * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in + * multiples of this size, defaulting to 1024. + * + * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); + +#define SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER "SDL.iostream.dynamic.memory" +#define SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER "SDL.iostream.dynamic.chunksize" + +/* @} *//* IOFrom functions */ + + +/** + * Create a custom SDL_IOStream. + * + * Applications do not need to use this function unless they are providing + * their own SDL_IOStream implementation. If you just need an SDL_IOStream to + * read/write a common data source, you should use the built-in + * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. + * + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. + * \returns a pointer to the allocated memory on success or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE + * \sa SDL_IOFromConstMem + * \sa SDL_IOFromFile + * \sa SDL_IOFromMem + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata); + +/** + * Close and free an allocated SDL_IOStream structure. + * + * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any + * resources used by the stream and frees the SDL_IOStream itself. This + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). + * + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. + * + * \param context SDL_IOStream structure to close. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); + +/** + * Get the properties associated with an SDL_IOStream. + * + * \param context a pointer to an SDL_IOStream structure. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); + +/** + * Query the stream status of an SDL_IOStream. + * + * This information can be useful to decide if a short read or write was due + * to an error, an EOF, or a non-blocking operation that isn't yet ready to + * complete. + * + * An SDL_IOStream's status is only expected to change after a SDL_ReadIO or + * SDL_WriteIO call; don't expect it to change if you just call this query + * function in a tight loop. + * + * \param context the SDL_IOStream to query. + * \returns an SDL_IOStatus enum with the current state. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); + +/** + * Use this function to get the size of the data stream in an SDL_IOStream. + * + * \param context the SDL_IOStream to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); + +/** + * Seek within an SDL_IOStream data stream. + * + * This function seeks to byte `offset`, relative to `whence`. + * + * `whence` may be any of the following values: + * + * - `SDL_IO_SEEK_SET`: seek from the beginning of data + * - `SDL_IO_SEEK_CUR`: seek relative to current read point + * - `SDL_IO_SEEK_END`: seek relative to the end of data + * + * If this stream can not seek, it will return -1. + * + * \param context a pointer to an SDL_IOStream structure. + * \param offset an offset in bytes, relative to `whence` location; can be + * negative. + * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, + * `SDL_IO_SEEK_END`. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TellIO + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence); + +/** + * Determine the current read/write offset in an SDL_IOStream data stream. + * + * SDL_TellIO is actually a wrapper function that calls the SDL_IOStream's + * `seek` method, with an offset of 0 bytes from `SDL_IO_SEEK_CUR`, to + * simplify application development. + * + * \param context an SDL_IOStream data stream object from which to get the + * current offset. + * \returns the current offset in the stream, or -1 if the information can not + * be determined. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SeekIO + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); + +/** + * Read from a data source. + * + * This function reads up `size` bytes from the data source to the area + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. + * + * \param context a pointer to an SDL_IOStream structure. + * \param ptr a pointer to a buffer to read data into. + * \param size the number of bytes to read from the data source. + * \returns the number of bytes read, or 0 on end of file or other failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteIO + * \sa SDL_GetIOStatus + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size); + +/** + * Write to an SDL_IOStream data stream. + * + * This function writes exactly `size` bytes from the area pointed at by `ptr` + * to the stream. If this fails for any reason, it'll return less than `size` + * to demonstrate how far the write progressed. On success, it returns `size`. + * + * On error, this function still attempts to write as much as possible, so it + * might return a positive value less than the requested write size. + * + * The caller can use SDL_GetIOStatus() to determine if the problem is + * recoverable, such as a non-blocking write that can simply be retried later, + * or a fatal error. + * + * \param context a pointer to an SDL_IOStream structure. + * \param ptr a pointer to a buffer containing data to write. + * \param size the number of bytes to write. + * \returns the number of bytes written, which will be less than `size` on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOprintf + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_FlushIO + * \sa SDL_GetIOStatus + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); + +/** + * Print to an SDL_IOStream data stream. + * + * This function does formatted printing to the stream. + * + * \param context a pointer to an SDL_IOStream structure. + * \param fmt a printf() style format string. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns the number of bytes written or 0 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOvprintf + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Print to an SDL_IOStream data stream. + * + * This function does formatted printing to the stream. + * + * \param context a pointer to an SDL_IOStream structure. + * \param fmt a printf() style format string. + * \param ap a variable argument list. + * \returns the number of bytes written or 0 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOprintf + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + +/** + * Load all the data from an SDL data stream. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param src the SDL_IOStream to read all available data from. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO + */ +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); + +/** + * Load all the data from a file path. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param file the path to read all available data from. + * \param datasize if not NULL, will store the number of bytes read. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile + */ +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); + +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + +/** + * \name Read endian functions + * + * Read an item of the specified endianness and return in native format. + */ +/* @{ */ + +/** + * Use this function to read a byte from an SDL_IOStream. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the SDL_IOStream to read from. + * \param value a pointer filled in with the data read. + * \returns true on success or false on failure or EOF; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); + +/** + * Use this function to read a signed byte from an SDL_IOStream. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the SDL_IOStream to read from. + * \param value a pointer filled in with the data read. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); + +/** + * Use this function to read 16 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); + +/** + * Use this function to read 16 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); + +/** + * Use this function to read 32 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); + +/** + * Use this function to read 32 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); + +/** + * Use this function to read 32 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); + +/** + * Use this function to read 32 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); + +/** + * Use this function to read 64 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); + +/** + * Use this function to read 64 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); + +/** + * Use this function to read 64 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); + +/** + * Use this function to read 64 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +/* @} *//* Read endian functions */ + +/** + * \name Write endian functions + * + * Write an item of native format to the specified endianness. + */ +/* @{ */ + +/** + * Use this function to write a byte to an SDL_IOStream. + * + * \param dst the SDL_IOStream to write to. + * \param value the byte value to write. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); + +/** + * Use this function to write a signed byte to an SDL_IOStream. + * + * \param dst the SDL_IOStream to write to. + * \param value the byte value to write. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); + +/** + * Use this function to write 16 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); + +/** + * Use this function to write 16 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); + +/** + * Use this function to write 16 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); + +/** + * Use this function to write 16 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); + +/** + * Use this function to write 32 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); + +/** + * Use this function to write 32 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); + +/** + * Use this function to write 32 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); + +/** + * Use this function to write 32 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); + +/** + * Use this function to write 64 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); + +/** + * Use this function to write 64 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); + +/** + * Use this function to write 64 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); + +/** + * Use this function to write 64 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); + +/* @} *//* Write endian functions */ + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_iostream_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_joystick.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_joystick.h new file mode 100644 index 0000000000..d15668b66a --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_joystick.h @@ -0,0 +1,1202 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryJoystick + * + * SDL joystick support. + * + * This is the lower-level joystick handling. If you want the simpler option, + * where what each button does is well-defined, you should use the gamepad API + * instead. + * + * The term "instance_id" is the current instantiation of a joystick device in + * the system, if the joystick is removed and then re-inserted then it will + * get a new instance_id, instance_id's are monotonically increasing + * identifiers of a joystick plugged in. + * + * The term "player_index" is the number assigned to a player on a specific + * controller. For XInput controllers this returns the XInput user index. Many + * joysticks will not be able to supply this information. + * + * SDL_GUID is used as a stable 128-bit identifier for a joystick device that + * does not change over time. It identifies class of the device (a X360 wired + * controller for example). This identifier is platform dependent. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks, + * and load appropriate drivers. + * + * If you would like to receive joystick updates while the application is in + * the background, you should set the following hint before calling + * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + */ + +#ifndef SDL_joystick_h_ +#define SDL_joystick_h_ + +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +#ifdef SDL_THREAD_SAFETY_ANALYSIS +/* + * This is not an exported symbol from SDL, this is only in the headers to + * help Clang's thread safety analysis tools to function. Do not attempt + * to access this symbol from your app, it will not work! + */ +extern SDL_Mutex *SDL_joystick_lock; +#endif + +/** + * The joystick structure used to identify an SDL joystick. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Joystick SDL_Joystick; + +/** + * This is a unique ID for a joystick for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the joystick is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_JoystickID; + +/** + * An enum of some common joystick types. + * + * In some cases, SDL can identify a low-level joystick as being a certain + * type of device, and will report it through SDL_GetJoystickType (or + * SDL_GetJoystickTypeForID). + * + * This is by no means a complete list of everything that can be plugged into + * a computer. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_JoystickType +{ + SDL_JOYSTICK_TYPE_UNKNOWN, + SDL_JOYSTICK_TYPE_GAMEPAD, + SDL_JOYSTICK_TYPE_WHEEL, + SDL_JOYSTICK_TYPE_ARCADE_STICK, + SDL_JOYSTICK_TYPE_FLIGHT_STICK, + SDL_JOYSTICK_TYPE_DANCE_PAD, + SDL_JOYSTICK_TYPE_GUITAR, + SDL_JOYSTICK_TYPE_DRUM_KIT, + SDL_JOYSTICK_TYPE_ARCADE_PAD, + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT +} SDL_JoystickType; + +/** + * Possible connection states for a joystick device. + * + * This is used by SDL_GetJoystickConnectionState to report how a device is + * connected to the system. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_JoystickConnectionState +{ + SDL_JOYSTICK_CONNECTION_INVALID = -1, + SDL_JOYSTICK_CONNECTION_UNKNOWN, + SDL_JOYSTICK_CONNECTION_WIRED, + SDL_JOYSTICK_CONNECTION_WIRELESS +} SDL_JoystickConnectionState; + +/** + * The largest value an SDL_Joystick's axis can report. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_JOYSTICK_AXIS_MIN + */ +#define SDL_JOYSTICK_AXIS_MAX 32767 + +/** + * The smallest value an SDL_Joystick's axis can report. + * + * This is a negative number! + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_JOYSTICK_AXIS_MAX + */ +#define SDL_JOYSTICK_AXIS_MIN -32768 + + +/* Function prototypes */ + +/** + * Locking for atomic access to the joystick API. + * + * The SDL joystick functions are thread-safe, however you can lock the + * joysticks while processing to guarantee that the joystick list won't change + * and joystick and gamepad events will not be delivered. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); + +/** + * Unlocking for atomic access to the joystick API. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); + +/** + * Return whether a joystick is currently connected. + * + * \returns true if a joystick is connected, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); + +/** + * Get a list of currently connected joysticks. + * + * \param count a pointer filled in with the number of joysticks returned, may + * be NULL. + * \returns a 0 terminated array of joystick instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasJoystick + * \sa SDL_OpenJoystick + */ +extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); + +/** + * Get the implementation dependent name of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param instance_id the joystick instance ID. + * \returns the name of the selected joystick. If no name can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickName + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID instance_id); + +/** + * Get the implementation dependent path of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param instance_id the joystick instance ID. + * \returns the path of the selected joystick. If no path can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickPath + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID instance_id); + +/** + * Get the player index of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param instance_id the joystick instance ID. + * \returns the player index of a joystick, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickPlayerIndex + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID instance_id); + +/** + * Get the implementation-dependent GUID of a joystick. + * + * This can be called before any joysticks are opened. + * + * \param instance_id the joystick instance ID. + * \returns the GUID of the selected joystick. If called with an invalid + * instance_id, this function returns a zero GUID. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickGUID + * \sa SDL_GUIDToString + */ +extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID instance_id); + +/** + * Get the USB vendor ID of a joystick, if available. + * + * This can be called before any joysticks are opened. If the vendor ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB vendor ID of the selected joystick. If called with an + * invalid instance_id, this function returns 0. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickVendor + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID instance_id); + +/** + * Get the USB product ID of a joystick, if available. + * + * This can be called before any joysticks are opened. If the product ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB product ID of the selected joystick. If called with an + * invalid instance_id, this function returns 0. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickProduct + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID instance_id); + +/** + * Get the product version of a joystick, if available. + * + * This can be called before any joysticks are opened. If the product version + * isn't available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the product version of the selected joystick. If called with an + * invalid instance_id, this function returns 0. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickProductVersion + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_JoystickID instance_id); + +/** + * Get the type of a joystick, if available. + * + * This can be called before any joysticks are opened. + * + * \param instance_id the joystick instance ID. + * \returns the SDL_JoystickType of the selected joystick. If called with an + * invalid instance_id, this function returns + * `SDL_JOYSTICK_TYPE_UNKNOWN`. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickType + * \sa SDL_GetJoysticks + */ +extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_JoystickID instance_id); + +/** + * Open a joystick for use. + * + * The joystick subsystem must be initialized before a joystick can be opened + * for use. + * + * \param instance_id the joystick instance ID. + * \returns a joystick identifier or NULL on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseJoystick + */ +extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_id); + +/** + * Get the SDL_Joystick associated with an instance ID, if it has been opened. + * + * \param instance_id the instance ID to get the SDL_Joystick for. + * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been + * opened yet; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); + +/** + * Get the SDL_Joystick associated with a player index. + * + * \param player_index the player index to get the SDL_Joystick for. + * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickPlayerIndex + * \sa SDL_SetJoystickPlayerIndex + */ +extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int player_index); + +/** + * The structure that describes a virtual joystick touchpad. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_VirtualJoystickDesc + */ +typedef struct SDL_VirtualJoystickTouchpadDesc +{ + Uint16 nfingers; /**< the number of simultaneous fingers on this touchpad */ + Uint16 padding[3]; +} SDL_VirtualJoystickTouchpadDesc; + +/** + * The structure that describes a virtual joystick sensor. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_VirtualJoystickDesc + */ +typedef struct SDL_VirtualJoystickSensorDesc +{ + SDL_SensorType type; /**< the type of this sensor */ + float rate; /**< the update frequency of this sensor, may be 0.0f */ +} SDL_VirtualJoystickSensorDesc; + +/** + * The structure that describes a virtual joystick. + * + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE + * \sa SDL_VirtualJoystickSensorDesc + * \sa SDL_VirtualJoystickTouchpadDesc + */ +typedef struct SDL_VirtualJoystickDesc +{ + Uint32 version; /**< the version of this interface */ + Uint16 type; /**< `SDL_JoystickType` */ + Uint16 padding; /**< unused */ + Uint16 vendor_id; /**< the USB vendor ID of this joystick */ + Uint16 product_id; /**< the USB product ID of this joystick */ + Uint16 naxes; /**< the number of axes on this joystick */ + Uint16 nbuttons; /**< the number of buttons on this joystick */ + Uint16 nballs; /**< the number of balls on this joystick */ + Uint16 nhats; /**< the number of hats on this joystick */ + Uint16 ntouchpads; /**< the number of touchpads on this joystick, requires `touchpads` to point at valid descriptions */ + Uint16 nsensors; /**< the number of sensors on this joystick, requires `sensors` to point at valid descriptions */ + Uint16 padding2[2]; /**< unused */ + Uint32 button_mask; /**< A mask of which buttons are valid for this controller + e.g. (1 << SDL_GAMEPAD_BUTTON_SOUTH) */ + Uint32 axis_mask; /**< A mask of which axes are valid for this controller + e.g. (1 << SDL_GAMEPAD_AXIS_LEFTX) */ + const char *name; /**< the name of the joystick */ + const SDL_VirtualJoystickTouchpadDesc *touchpads; /**< A pointer to an array of touchpad descriptions, required if `ntouchpads` is > 0 */ + const SDL_VirtualJoystickSensorDesc *sensors; /**< A pointer to an array of sensor descriptions, required if `nsensors` is > 0 */ + + void *userdata; /**< User data pointer passed to callbacks */ + void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ + void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ +} SDL_VirtualJoystickDesc; + +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + +/** + * Attach a new virtual joystick. + * + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). + * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DetachVirtualJoystick + */ +extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_VirtualJoystickDesc *desc); + +/** + * Detach a virtual joystick. + * + * \param instance_id the joystick instance ID, previously returned from + * SDL_AttachVirtualJoystick(). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AttachVirtualJoystick + */ +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); + +/** + * Query whether or not a joystick is virtual. + * + * \param instance_id the joystick instance ID. + * \returns true if the joystick is virtual, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); + +/** + * Set the state of an axis on an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * Note that when sending trigger axes, you should scale the value to the full + * range of Sint16. For example, a trigger at rest would have the value of + * `SDL_JOYSTICK_AXIS_MIN`. + * + * \param joystick the virtual joystick on which to set state. + * \param axis the index of the axis on the virtual joystick to update. + * \param value the new value for the specified axis. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); + +/** + * Generate ball motion on an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param ball the index of the ball on the virtual joystick to update. + * \param xrel the relative motion on the X axis. + * \param yrel the relative motion on the Y axis. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); + +/** + * Set the state of a button on an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param button the index of the button on the virtual joystick to update. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); + +/** + * Set the state of a hat on an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param hat the index of the hat on the virtual joystick to update. + * \param value the new value for the specified hat. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); + +/** + * Set touchpad finger state on an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param touchpad the index of the touchpad on the virtual joystick to + * update. + * \param finger the index of the finger on the touchpad to set. + * \param down true if the finger is pressed, false if the finger is released. + * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, + * with the origin in the upper left. + * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, + * with the origin in the upper left. + * \param pressure the pressure of the finger. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); + +/** + * Send a sensor update for an opened virtual joystick. + * + * Please note that values set here will not be applied until the next call to + * SDL_UpdateJoysticks, which can either be called directly, or can be called + * indirectly through various other SDL APIs, including, but not limited to + * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, + * SDL_WaitEvent. + * + * \param joystick the virtual joystick on which to set state. + * \param type the type of the sensor on the virtual joystick to update. + * \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with + * the sensor reading. + * \param data the data associated with the sensor reading. + * \param num_values the number of values pointed to by `data`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); + +/** + * Get the properties associated with a joystick. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN`: true if this joystick has an + * LED that has adjustable brightness + * - `SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN`: true if this joystick has an LED + * that has adjustable color + * - `SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN`: true if this joystick has a + * player LED + * - `SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN`: true if this joystick has + * left/right rumble + * - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has + * simple trigger rumble + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); + +#define SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN "SDL.joystick.cap.mono_led" +#define SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN "SDL.joystick.cap.rgb_led" +#define SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN "SDL.joystick.cap.player_led" +#define SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN "SDL.joystick.cap.rumble" +#define SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN "SDL.joystick.cap.trigger_rumble" + +/** + * Get the implementation dependent name of a joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the name of the selected joystick. If no name can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickNameForID + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick); + +/** + * Get the implementation dependent path of a joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the path of the selected joystick. If no path can be found, this + * function returns NULL; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickPathForID + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick); + +/** + * Get the player index of an opened joystick. + * + * For XInput controllers this returns the XInput user index. Many joysticks + * will not be able to supply this information. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the player index, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickPlayerIndex + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystick); + +/** + * Set the player index of an opened joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \param player_index player index to assign to this joystick, or -1 to clear + * the player index and turn off player LEDs. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickPlayerIndex + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); + +/** + * Get the implementation-dependent GUID for the joystick. + * + * This function requires an open joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the GUID of the given joystick. If called on an invalid index, + * this function returns a zero GUID; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickGUIDForID + * \sa SDL_GUIDToString + */ +extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick); + +/** + * Get the USB vendor ID of an opened joystick, if available. + * + * If the vendor ID isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickVendorForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick); + +/** + * Get the USB product ID of an opened joystick, if available. + * + * If the product ID isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the USB product ID of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickProductForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick); + +/** + * Get the product version of an opened joystick, if available. + * + * If the product version isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the product version of the selected joystick, or 0 if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickProductVersionForID + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *joystick); + +/** + * Get the firmware version of an opened joystick, if available. + * + * If the firmware version isn't available this function returns 0. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the firmware version of the selected joystick, or 0 if + * unavailable. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); + +/** + * Get the serial number of an opened joystick, if available. + * + * Returns the serial number of the joystick, or NULL if it is not available. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the serial number of the selected joystick, or NULL if + * unavailable. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); + +/** + * Get the type of an opened joystick. + * + * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). + * \returns the SDL_JoystickType of the selected joystick. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickTypeForID + */ +extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joystick); + +/** + * Get the device information encoded in a SDL_GUID structure. + * + * \param guid the SDL_GUID you wish to get info about. + * \param vendor a pointer filled in with the device VID, or 0 if not + * available. + * \param product a pointer filled in with the device PID, or 0 if not + * available. + * \param version a pointer filled in with the device version, or 0 if not + * available. + * \param crc16 a pointer filled in with a CRC used to distinguish different + * products with the same VID/PID, or 0 if not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickGUIDForID + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16); + +/** + * Get the status of a specified joystick. + * + * \param joystick the joystick to query. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); + +/** + * Get the instance ID of an opened joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \returns the instance ID of the specified joystick on success or 0 on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); + +/** + * Get the number of general axis controls on a joystick. + * + * Often, the directional pad on a game controller will either look like 4 + * separate buttons or a POV hat, and not axes, but all of this is up to the + * device and platform. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \returns the number of axis controls/number of axes on success or -1 on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickAxis + * \sa SDL_GetNumJoystickBalls + * \sa SDL_GetNumJoystickButtons + * \sa SDL_GetNumJoystickHats + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); + +/** + * Get the number of trackballs on a joystick. + * + * Joystick trackballs have only relative motion events associated with them + * and their state cannot be polled. + * + * Most joysticks do not have trackballs. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \returns the number of trackballs on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickBall + * \sa SDL_GetNumJoystickAxes + * \sa SDL_GetNumJoystickButtons + * \sa SDL_GetNumJoystickHats + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); + +/** + * Get the number of POV hats on a joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \returns the number of POV hats on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickHat + * \sa SDL_GetNumJoystickAxes + * \sa SDL_GetNumJoystickBalls + * \sa SDL_GetNumJoystickButtons + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); + +/** + * Get the number of buttons on a joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \returns the number of buttons on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickButton + * \sa SDL_GetNumJoystickAxes + * \sa SDL_GetNumJoystickBalls + * \sa SDL_GetNumJoystickHats + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick); + +/** + * Set the state of joystick event processing. + * + * If joystick events are disabled, you must call SDL_UpdateJoysticks() + * yourself and check the state of the joystick when you want joystick + * information. + * + * \param enabled whether to process joystick events or not. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_JoystickEventsEnabled + * \sa SDL_UpdateJoysticks + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); + +/** + * Query the state of joystick event processing. + * + * If joystick events are disabled, you must call SDL_UpdateJoysticks() + * yourself and check the state of the joystick when you want joystick + * information. + * + * \returns true if joystick events are being processed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickEventsEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); + +/** + * Update the current state of the open joysticks. + * + * This is called automatically by the event loop if any joystick events are + * enabled. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); + +/** + * Get the current state of an axis control on a joystick. + * + * SDL makes no promises about what part of the joystick any given axis refers + * to. Your game should have some sort of configuration UI to let users + * specify what each axis should be bound to. Alternately, SDL's higher-level + * Game Controller API makes a great effort to apply order to this lower-level + * interface, so you know that a specific axis is the "left thumb stick," etc. + * + * The value returned by SDL_GetJoystickAxis() is a signed integer (-32768 to + * 32767) representing the current position of the axis. It may be necessary + * to impose certain tolerances on these values to account for jitter. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \param axis the axis to query; the axis indices start at index 0. + * \returns a 16-bit signed integer representing the current position of the + * axis or 0 on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumJoystickAxes + */ +extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, int axis); + +/** + * Get the initial state of an axis control on a joystick. + * + * The state is a value ranging from -32768 to 32767. + * + * The axis indices start at index 0. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \param axis the axis to query; the axis indices start at index 0. + * \param state upon return, the initial value is supplied here. + * \returns true if this axis has any initial value, or false if not. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); + +/** + * Get the ball axis change since the last poll. + * + * Trackballs can only return relative motion since the last call to + * SDL_GetJoystickBall(), these motion deltas are placed into `dx` and `dy`. + * + * Most joysticks do not have trackballs. + * + * \param joystick the SDL_Joystick to query. + * \param ball the ball index to query; ball indices start at index 0. + * \param dx stores the difference in the x axis position since the last poll. + * \param dy stores the difference in the y axis position since the last poll. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumJoystickBalls + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); + +/** + * Get the current state of a POV hat on a joystick. + * + * The returned value will be one of the `SDL_HAT_*` values. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \param hat the hat index to get the state from; indices start at index 0. + * \returns the current hat position. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumJoystickHats + */ +extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int hat); + +#define SDL_HAT_CENTERED 0x00u +#define SDL_HAT_UP 0x01u +#define SDL_HAT_RIGHT 0x02u +#define SDL_HAT_DOWN 0x04u +#define SDL_HAT_LEFT 0x08u +#define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) +#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) +#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) +#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) + +/** + * Get the current state of a button on a joystick. + * + * \param joystick an SDL_Joystick structure containing joystick information. + * \param button the button index to get the state from; indices start at + * index 0. + * \returns true if the button is pressed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumJoystickButtons + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); + +/** + * Start a rumble effect. + * + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param joystick the joystick to vibrate. + * \param low_frequency_rumble the intensity of the low frequency (left) + * rumble motor, from 0 to 0xFFFF. + * \param high_frequency_rumble the intensity of the high frequency (right) + * rumble motor, from 0 to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true, or false if rumble isn't supported on this joystick. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); + +/** + * Start a rumble effect in the joystick's triggers. + * + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. + * + * Note that this is rumbling of the _triggers_ and not the game controller as + * a whole. This is currently only supported on Xbox One controllers. If you + * want the (more common) whole-controller rumble, use SDL_RumbleJoystick() + * instead. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param joystick the joystick to vibrate. + * \param left_rumble the intensity of the left trigger rumble motor, from 0 + * to 0xFFFF. + * \param right_rumble the intensity of the right trigger rumble motor, from 0 + * to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RumbleJoystick + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); + +/** + * Update a joystick's LED color. + * + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. + * + * For joysticks with a single color LED, the maximum of the RGB values will + * be used as the LED brightness. + * + * \param joystick the joystick to update. + * \param red the intensity of the red LED. + * \param green the intensity of the green LED. + * \param blue the intensity of the blue LED. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); + +/** + * Send a joystick specific effect packet. + * + * \param joystick the joystick to affect. + * \param data the data to send to the joystick. + * \param size the size of the data to send to the joystick. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); + +/** + * Close a joystick previously opened with SDL_OpenJoystick(). + * + * \param joystick the joystick device to close. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenJoystick + */ +extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); + +/** + * Get the connection state of a joystick. + * + * \param joystick the joystick to query. + * \returns the connection state on success or + * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); + +/** + * Get the battery state of a joystick. + * + * You should never take a battery status as absolute truth. Batteries + * (especially failing batteries) are delicate hardware, and the values + * reported here are best estimates based on what that hardware reports. It's + * not uncommon for older batteries to lose stored power much faster than it + * reports, or completely drain when reporting it has 20 percent left, etc. + * + * \param joystick the joystick to query. + * \param percent a pointer filled in with the percentage of battery life + * left, between 0 and 100, or NULL to ignore. This will be + * filled in with -1 we can't determine a value or there is no + * battery. + * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_joystick_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keyboard.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keyboard.h new file mode 100644 index 0000000000..afa77b6c2c --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keyboard.h @@ -0,0 +1,609 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryKeyboard + * + * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices + */ + +#ifndef SDL_keyboard_h_ +#define SDL_keyboard_h_ + +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * This is a unique ID for a keyboard for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the keyboard is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_KeyboardID; + +/* Function prototypes */ + +/** + * Return whether a keyboard is currently connected. + * + * \returns true if a keyboard is connected, false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyboards + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); + +/** + * Get a list of currently connected keyboards. + * + * Note that this will include any device or virtual driver that includes + * keyboard functionality, including some mice, KVM switches, motherboard + * power buttons, etc. You should wait for input from a device before you + * consider it actively in use. + * + * \param count a pointer filled in with the number of keyboards returned, may + * be NULL. + * \returns a 0 terminated array of keyboards instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyboardNameForID + * \sa SDL_HasKeyboard + */ +extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); + +/** + * Get the name of a keyboard. + * + * This function returns "" if the keyboard doesn't have a name. + * + * \param instance_id the keyboard instance ID. + * \returns the name of the selected keyboard or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyboards + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id); + +/** + * Query the window which currently has keyboard focus. + * + * \returns the window with keyboard focus. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); + +/** + * Get a snapshot of the current state of the keyboard. + * + * The pointer returned is a pointer to an internal SDL array. It will be + * valid for the whole lifetime of the application and should not be freed by + * the caller. + * + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. + * + * Use SDL_PumpEvents() to update the state array. + * + * This function gives you the current state after all events have been + * processed, so if a key or button has been pressed and released before you + * process events, then the pressed state will never show up in the + * SDL_GetKeyboardState() calls. + * + * Note: This function doesn't take into account whether shift has been + * pressed or not. + * + * \param numkeys if non-NULL, receives the length of the returned array. + * \returns a pointer to an array of key states. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PumpEvents + * \sa SDL_ResetKeyboard + */ +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); + +/** + * Clear the state of the keyboard. + * + * This function will generate key up events for all pressed keys. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyboardState + */ +extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); + +/** + * Get the current key modifier state for the keyboard. + * + * \returns an OR'd combination of the modifier keys for the keyboard. See + * SDL_Keymod for details. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyboardState + * \sa SDL_SetModState + */ +extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); + +/** + * Set the current key modifier state for the keyboard. + * + * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose + * modifier key states on your application. Simply pass your desired modifier + * states into `modstate`. This value may be a bitwise, OR'd combination of + * SDL_Keymod values. + * + * This does not change the keyboard state, only the key modifier flags that + * SDL reports. + * + * \param modstate the desired SDL_Keymod for the keyboard. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetModState + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); + +/** + * Get the key code corresponding to the given scancode according to the + * current keyboard layout. + * + * If you want to get the keycode as it would be delivered in key events, + * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should + * pass `key_event` as true. Otherwise this function simply translates the + * scancode based on the given modifier state. + * + * \param scancode the desired SDL_Scancode to query. + * \param modstate the modifier state to use when translating the scancode to + * a keycode. + * \param key_event true if the keycode will be used in key events. + * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyName + * \sa SDL_GetScancodeFromKey + */ +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); + +/** + * Get the scancode corresponding to the given key code according to the + * current keyboard layout. + * + * Note that there may be multiple scancode+modifier states that can generate + * this keycode, this will just return the first one found. + * + * \param key the desired SDL_Keycode to query. + * \param modstate a pointer to the modifier state that would be used when the + * scancode generates this key, may be NULL. + * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetScancodeName + */ +extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate); + +/** + * Set a human-readable name for a scancode. + * + * \param scancode the desired SDL_Scancode. + * \param name the name to use for the scancode, encoded as UTF-8. The string + * is not copied, so the pointer given to this function must stay + * valid while SDL is being used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetScancodeName + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); + +/** + * Get a human-readable name for a scancode. + * + * **Warning**: The returned name is by design not stable across platforms, + * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left + * Windows" under Microsoft Windows, and some scancodes like + * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even + * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and + * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore + * unsuitable for creating a stable cross-platform two-way mapping between + * strings and scancodes. + * + * \param scancode the desired SDL_Scancode to query. + * \returns a pointer to the name for the scancode. If the scancode doesn't + * have a name this function returns an empty string (""). + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetScancodeFromKey + * \sa SDL_GetScancodeFromName + * \sa SDL_SetScancodeName + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); + +/** + * Get a scancode from a human-readable name. + * + * \param name the human-readable scancode name. + * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't + * recognized; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyFromName + * \sa SDL_GetScancodeFromKey + * \sa SDL_GetScancodeName + */ +extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); + +/** + * Get a human-readable name for a key. + * + * If the key doesn't have a name, this function returns an empty string (""). + * + * Letters will be presented in their uppercase form, if applicable. + * + * \param key the desired SDL_Keycode to query. + * \returns a UTF-8 encoded string of the key name. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyFromName + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetScancodeFromKey + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); + +/** + * Get a key code from a human-readable name. + * + * \param name the human-readable key name. + * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call + * SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetKeyFromScancode + * \sa SDL_GetKeyName + * \sa SDL_GetScancodeFromName + */ +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); + +/** + * Start accepting Unicode text input events in a window. + * + * This function will enable text input (SDL_EVENT_TEXT_INPUT and + * SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this + * function paired with SDL_StopTextInput(). + * + * Text input events are not received by default. + * + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. + * + * \param window the window to enable text input. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTextInputArea + * \sa SDL_StartTextInputWithProperties + * \sa SDL_StopTextInput + * \sa SDL_TextInputActive + */ +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); + +/** + * Text input type. + * + * These are the valid values for SDL_PROP_TEXTINPUT_TYPE_NUMBER. Not every + * value is valid on every platform, but where a value isn't supported, a + * reasonable fallback will be used. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_StartTextInputWithProperties + */ +typedef enum SDL_TextInputType +{ + SDL_TEXTINPUT_TYPE_TEXT, /**< The input is text */ + SDL_TEXTINPUT_TYPE_TEXT_NAME, /**< The input is a person's name */ + SDL_TEXTINPUT_TYPE_TEXT_EMAIL, /**< The input is an e-mail address */ + SDL_TEXTINPUT_TYPE_TEXT_USERNAME, /**< The input is a username */ + SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN, /**< The input is a secure password that is hidden */ + SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE, /**< The input is a secure password that is visible */ + SDL_TEXTINPUT_TYPE_NUMBER, /**< The input is a number */ + SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN, /**< The input is a secure PIN that is hidden */ + SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE /**< The input is a secure PIN that is visible */ +} SDL_TextInputType; + +/** + * Auto capitalization type. + * + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_StartTextInputWithProperties + */ +typedef enum SDL_Capitalization +{ + SDL_CAPITALIZE_NONE, /**< No auto-capitalization will be done */ + SDL_CAPITALIZE_SENTENCES, /**< The first letter of sentences will be capitalized */ + SDL_CAPITALIZE_WORDS, /**< The first letter of words will be capitalized */ + SDL_CAPITALIZE_LETTERS /**< All letters will be capitalized */ +} SDL_Capitalization; + +/** + * Start accepting Unicode text input events in a window, with properties + * describing the input. + * + * This function will enable text input (SDL_EVENT_TEXT_INPUT and + * SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this + * function paired with SDL_StopTextInput(). + * + * Text input events are not received by default. + * + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. + * + * These are the supported properties: + * + * - `SDL_PROP_TEXTINPUT_TYPE_NUMBER` - an SDL_TextInputType value that + * describes text being input, defaults to SDL_TEXTINPUT_TYPE_TEXT. + * - `SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER` - an SDL_Capitalization value + * that describes how text should be capitalized, defaults to + * SDL_CAPITALIZE_SENTENCES for normal text entry, SDL_CAPITALIZE_WORDS for + * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail + * addresses, usernames, and passwords. + * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion + * and auto correction, defaults to true. + * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". + * + * On Android you can directly specify the input type: + * + * - `SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER` - the text input type to + * use, overriding other properties. This is documented at + * https://developer.android.com/reference/android/text/InputType + * + * \param window the window to enable text input. + * \param props the properties to use. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTextInputArea + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput + * \sa SDL_TextInputActive + */ +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); + +#define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" +#define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" +#define SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN "SDL.textinput.autocorrect" +#define SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN "SDL.textinput.multiline" +#define SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER "SDL.textinput.android.inputtype" + +/** + * Check whether or not Unicode text input events are enabled for a window. + * + * \param window the window to check. + * \returns true if text input events are enabled else false. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StartTextInput + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); + +/** + * Stop receiving any text input events in a window. + * + * If SDL_StartTextInput() showed the screen keyboard, this function will hide + * it. + * + * \param window the window to disable text input. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StartTextInput + */ +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); + +/** + * Dismiss the composition window/IME without disabling the subsystem. + * + * \param window the window to affect. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StartTextInput + * \sa SDL_StopTextInput + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); + +/** + * Set the area used to type Unicode text input. + * + * Native input methods may place a window with word suggestions near the + * cursor, without covering the text being entered. + * + * \param window the window for which to set the text input area. + * \param rect the SDL_Rect representing the text input area, in window + * coordinates, or NULL to clear it. + * \param cursor the offset of the current cursor location relative to + * `rect->x`, in window coordinates. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextInputArea + * \sa SDL_StartTextInput + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); + +/** + * Get the area used to type Unicode text input. + * + * This returns the values previously set by SDL_SetTextInputArea(). + * + * \param window the window for which to query the text input area. + * \param rect a pointer to an SDL_Rect filled in with the text input area, + * may be NULL. + * \param cursor a pointer to the offset of the current cursor location + * relative to `rect->x`, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTextInputArea + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); + +/** + * Check whether the platform has screen keyboard support. + * + * \returns true if the platform has some screen keyboard support or false if + * not. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StartTextInput + * \sa SDL_ScreenKeyboardShown + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); + +/** + * Check whether the screen keyboard is shown for given window. + * + * \param window the window for which screen keyboard should be queried. + * \returns true if screen keyboard is shown or false if not. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasScreenKeyboardSupport + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_keyboard_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keycode.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keycode.h new file mode 100644 index 0000000000..61b68e794f --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_keycode.h @@ -0,0 +1,343 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryKeycode + * + * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices + */ + +#ifndef SDL_keycode_h_ +#define SDL_keycode_h_ + +#include +#include + +/** + * The SDL virtual key representation. + * + * Values of this type are used to represent keyboard keys using the current + * layout of the keyboard. These values include Unicode values representing + * the unmodified character that would be generated by pressing the key, or an + * `SDLK_*` constant for those keys that do not generate characters. + * + * A special exception is the number keys at the top of the keyboard which map + * to SDLK_0...SDLK_9 on AZERTY layouts. + * + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_Keycode; + +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) +#define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ + +/** + * Valid key modifiers (possibly OR'd together). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint16 SDL_Keymod; + +#define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ +#define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ +#define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ +#define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ +#define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ +#define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ +#define SDL_KMOD_RALT 0x0200u /**< the right Alt key is down. */ +#define SDL_KMOD_LGUI 0x0400u /**< the left GUI key (often the Windows key) is down. */ +#define SDL_KMOD_RGUI 0x0800u /**< the right GUI key (often the Windows key) is down. */ +#define SDL_KMOD_NUM 0x1000u /**< the Num Lock key (may be located on an extended keypad) is down. */ +#define SDL_KMOD_CAPS 0x2000u /**< the Caps Lock key is down. */ +#define SDL_KMOD_MODE 0x4000u /**< the !AltGr key is down. */ +#define SDL_KMOD_SCROLL 0x8000u /**< the Scroll Lock key is down. */ +#define SDL_KMOD_CTRL (SDL_KMOD_LCTRL | SDL_KMOD_RCTRL) /**< Any Ctrl key is down. */ +#define SDL_KMOD_SHIFT (SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT) /**< Any Shift key is down. */ +#define SDL_KMOD_ALT (SDL_KMOD_LALT | SDL_KMOD_RALT) /**< Any Alt key is down. */ +#define SDL_KMOD_GUI (SDL_KMOD_LGUI | SDL_KMOD_RGUI) /**< Any GUI key is down. */ + +#endif /* SDL_keycode_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_loadso.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_loadso.h similarity index 59% rename from code/thirdparty/SDL2-2.32.8/include/SDL_loadso.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_loadso.h index 1763b52801..f8649d7580 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_loadso.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_loadso.h @@ -19,13 +19,21 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* WIKI CATEGORY: LoadSO */ +/* WIKI CATEGORY: SharedObject */ /** - * # CategoryLoadSO + * # CategorySharedObject * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,33 +46,51 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ #define SDL_loadso_h_ -#include "SDL_stdinc.h" -#include "SDL_error.h" +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * * \param sofile a system-dependent name of the object file. - * \returns an opaque pointer to the object handle or NULL if there was an - * error; call SDL_GetError() for more information. + * \returns an opaque pointer to the object handle or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -83,35 +109,37 @@ extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile); * * \param handle a valid shared object handle returned by SDL_LoadObject(). * \param name the name of the function to look up. - * \returns a pointer to the function or NULL if there was an error; call - * SDL_GetError() for more information. + * \returns a pointer to the function or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 2.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject - * \sa SDL_UnloadObject */ -extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle, - const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 2.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * - * \sa SDL_LoadFunction * \sa SDL_LoadObject */ -extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_loadso_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_locale.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_locale.h similarity index 64% rename from code/thirdparty/SDL2-2.32.8/include/SDL_locale.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_locale.h index 8126efc79a..902843e81f 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_locale.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_locale.h @@ -22,16 +22,22 @@ /** * # CategoryLocale * - * Include file for SDL locale services + * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ -#ifndef _SDL_locale_h -#define _SDL_locale_h +#ifndef SDL_locale_h +#define SDL_locale_h -#include "SDL_stdinc.h" -#include "SDL_error.h" +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus /* *INDENT-OFF* */ @@ -39,7 +45,18 @@ extern "C" { /* *INDENT-ON* */ #endif - +/** + * A struct to provide locale data. + * + * Locale data is split into a spoken language, like English, and an optional + * country, like Canada. The language will be in ISO-639 format (so English + * would be "en"), and the country, if not NULL, will be an ISO-3166 country + * code (so Canada would be "CA"). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPreferredLocales + */ typedef struct SDL_Locale { const char *language; /**< A language name, like "en" for English. */ @@ -49,11 +66,6 @@ typedef struct SDL_Locale /** * Report the user's preferred locale. * - * This returns an array of SDL_Locale structs, the final item zeroed out. - * When the caller is done with this array, it should call SDL_free() on the - * returned value; all the memory involved is allocated in a single block, so - * a single SDL_free() will suffice. - * * Returned language strings are in the format xx, where 'xx' is an ISO-639 * language specifier (such as "en" for English, "de" for German, etc). * Country strings are in the format YY, where "YY" is an ISO-3166 country @@ -79,16 +91,20 @@ typedef struct SDL_Locale * This might be a "slow" call that has to query the operating system. It's * best to ask for this once and save the results. However, this list can * change, usually because the user has changed a system preference outside of - * your program; SDL will send an SDL_LOCALECHANGED event in this case, if - * possible, and you can call this function again to get an updated copy of + * your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, + * if possible, and you can call this function again to get an updated copy of * preferred locales. * - * \return array of locales, terminated with a locale with a NULL language - * field. Will return NULL on error. + * \param count a pointer filled in with the number of locales returned, may + * be NULL. + * \returns a NULL terminated array of locale pointers, or NULL on failure; + * call SDL_GetError() for more information. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. * - * \since This function is available since SDL 2.0.14. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); +extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -96,8 +112,6 @@ extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); } /* *INDENT-ON* */ #endif -#include "close_code.h" - -#endif /* _SDL_locale_h */ +#include -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_locale_h */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_log.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_log.h new file mode 100644 index 0000000000..3fd7ec2ede --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_log.h @@ -0,0 +1,538 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryLog + * + * Simple log messages with priorities and categories. A message's + * SDL_LogPriority signifies how important the message is. A message's + * SDL_LogCategory signifies from what domain it belongs to. Every category + * has a minimum priority specified: when a message belongs to that category, + * it will only be sent out if it has that minimum priority or higher. + * + * SDL's own logs are sent below the default priority threshold, so they are + * quiet by default. + * + * You can change the log verbosity programmatically using + * SDL_SetLogPriority() or with SDL_SetHint(SDL_HINT_LOGGING, ...), or with + * the "SDL_LOGGING" environment variable. This variable is a comma separated + * set of category=level tokens that define the default logging levels for SDL + * applications. + * + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. + * + * The level can be a numeric level, one of "trace", "verbose", "debug", + * "info", "warn", "error", "critical", or "quiet" to disable that category. + * + * You can omit the category if you want to set the logging level for all + * categories. + * + * If this hint isn't set, the default log levels are equivalent to: + * + * `app=info,assert=warn,test=verbose,*=error` + * + * Here's where the messages go on different platforms: + * + * - Windows: debug output stream + * - Android: log output + * - Others: standard error output (stderr) + * + * You don't need to have a newline (`\n`) on the end of messages, the + * functions will do that for you. For consistent behavior cross-platform, you + * shouldn't have any newlines in messages, such as to log multiple lines in + * one call; unusual platform-specific behavior can be observed in such usage. + * Do one log call per line instead, with no newlines in messages. + * + * Each log call is atomic, so you won't see log messages cut off one another + * when logging from multiple threads. + */ + +#ifndef SDL_log_h_ +#define SDL_log_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The predefined log categories + * + * By default the application and gpu categories are enabled at the INFO + * level, the assert category is enabled at the WARN level, test is enabled at + * the VERBOSE level and all other categories are enabled at the ERROR level. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_LogCategory +{ + SDL_LOG_CATEGORY_APPLICATION, + SDL_LOG_CATEGORY_ERROR, + SDL_LOG_CATEGORY_ASSERT, + SDL_LOG_CATEGORY_SYSTEM, + SDL_LOG_CATEGORY_AUDIO, + SDL_LOG_CATEGORY_VIDEO, + SDL_LOG_CATEGORY_RENDER, + SDL_LOG_CATEGORY_INPUT, + SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, + + /* Reserved for future SDL library use */ + SDL_LOG_CATEGORY_RESERVED2, + SDL_LOG_CATEGORY_RESERVED3, + SDL_LOG_CATEGORY_RESERVED4, + SDL_LOG_CATEGORY_RESERVED5, + SDL_LOG_CATEGORY_RESERVED6, + SDL_LOG_CATEGORY_RESERVED7, + SDL_LOG_CATEGORY_RESERVED8, + SDL_LOG_CATEGORY_RESERVED9, + SDL_LOG_CATEGORY_RESERVED10, + + /* Beyond this point is reserved for application use, e.g. + enum { + MYAPP_CATEGORY_AWESOME1 = SDL_LOG_CATEGORY_CUSTOM, + MYAPP_CATEGORY_AWESOME2, + MYAPP_CATEGORY_AWESOME3, + ... + }; + */ + SDL_LOG_CATEGORY_CUSTOM +} SDL_LogCategory; + +/** + * The predefined log priorities + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_LogPriority +{ + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, + SDL_LOG_PRIORITY_DEBUG, + SDL_LOG_PRIORITY_INFO, + SDL_LOG_PRIORITY_WARN, + SDL_LOG_PRIORITY_ERROR, + SDL_LOG_PRIORITY_CRITICAL, + SDL_LOG_PRIORITY_COUNT +} SDL_LogPriority; + + +/** + * Set the priority of all log categories. + * + * \param priority the SDL_LogPriority to assign. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResetLogPriorities + * \sa SDL_SetLogPriority + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); + +/** + * Set the priority of a particular log category. + * + * \param category the category to assign a priority to. + * \param priority the SDL_LogPriority to assign. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetLogPriority + * \sa SDL_ResetLogPriorities + * \sa SDL_SetLogPriorities + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); + +/** + * Get the priority of a particular log category. + * + * \param category the category to query. + * \returns the SDL_LogPriority for the requested category. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogPriority + */ +extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); + +/** + * Reset all priorities to default. + * + * This is called by SDL_Quit(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogPriorities + * \sa SDL_SetLogPriority + */ +extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); + +/** + * Set the text prepended to log messages of a given priority. + * + * By default SDL_LOG_PRIORITY_INFO and below have no prefix, and + * SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g. + * "WARNING: ". + * + * \param priority the SDL_LogPriority to modify. + * \param prefix the prefix to use for that log priority, or NULL to use no + * prefix. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogPriorities + * \sa SDL_SetLogPriority + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); + +/** + * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. + * + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_VERBOSE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_DEBUG. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_INFO. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_WARN. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_ERROR. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with SDL_LOG_PRIORITY_CRITICAL. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * Log a message with the specified category and priority. + * + * \param category the category of the message. + * \param priority the priority of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, + SDL_LogPriority priority, + SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * Log a message with the specified category and priority. + * + * \param category the category of the message. + * \param priority the priority of the message. + * \param fmt a printf() style message format string. + * \param ap a variable argument list. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, + SDL_LogPriority priority, + SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); + +/** + * The prototype for the log output callback function. + * + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. + * + * \param userdata what was passed as `userdata` to + * SDL_SetLogOutputFunction(). + * \param category the category of the message. + * \param priority the priority of the message. + * \param message the message being output. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); + +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + +/** + * Get the current log output function. + * + * \param callback an SDL_LogOutputFunction filled in with the current log + * callback. + * \param userdata a pointer filled in with the pointer that is passed to + * `callback`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction + * \sa SDL_SetLogOutputFunction + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); + +/** + * Replace the default log output function with one of your own. + * + * \param callback an SDL_LogOutputFunction to call instead of the default. + * \param userdata a pointer that is passed to `callback`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_log_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main.h new file mode 100644 index 0000000000..905d78e964 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main.h @@ -0,0 +1,675 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryMain + * + * Redefine main() if necessary so that it is called by SDL. + * + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * #include + * #include + * + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * SDL_main.h is a "single-header library," which is to say that including + * this header inserts code into your program, and you should only include it + * once in most cases. SDL.h does not include this header automatically. + * + * For more information, see: + * + * https://wiki.libsdl.org/SDL3/README/main-functions + */ + +#ifndef SDL_main_h_ +#define SDL_main_h_ + +#include +#include +#include +#include + +#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.2.0. + */ +#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.2.0. + * + * \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.2.0. + */ +#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.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + +#ifndef SDL_MAIN_HANDLED + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) + /* On Windows SDL provides WinMain(), which parses the command line and passes + the arguments to your main function. + + If you provide your own WinMain(), you may define SDL_MAIN_HANDLED + */ + #define SDL_MAIN_AVAILABLE + + #elif defined(SDL_PLATFORM_GDK) + /* On GDK, SDL provides a main function that initializes the game runtime. + + If you prefer to write your own WinMain-function instead of having SDL + provide one that calls your main() function, + #define SDL_MAIN_HANDLED before #include'ing SDL_main.h + and call the SDL_RunApp function from your entry point. + */ + #define SDL_MAIN_NEEDED + + #elif defined(SDL_PLATFORM_IOS) + /* On iOS SDL provides a main function that creates an application delegate + and starts the iOS application run loop. + + To use it, just #include SDL_main.h in the source file that contains your + main() function. + + See src/video/uikit/SDL_uikitappdelegate.m for more details. + */ + #define SDL_MAIN_NEEDED + + #elif defined(SDL_PLATFORM_ANDROID) + /* On Android SDL provides a Java class in SDLActivity.java that is the + main activity entry point. + + See docs/README-android.md for more details on extending that class. + */ + #define SDL_MAIN_NEEDED + + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED + + #elif defined(SDL_PLATFORM_EMSCRIPTEN) + /* On Emscripten, SDL provides a main function that converts URL + parameters that start with "SDL_" to environment variables, so + they can be used as SDL hints, etc. + + This is 100% optional, so if you don't want this to happen, you may + define SDL_MAIN_HANDLED + */ + #define SDL_MAIN_AVAILABLE + + #elif defined(SDL_PLATFORM_PSP) + /* On PSP SDL provides a main function that sets the module info, + activates the GPU and starts the thread required to be able to exit + the software. + + If you provide this yourself, you may define SDL_MAIN_HANDLED + */ + #define SDL_MAIN_AVAILABLE + + #elif defined(SDL_PLATFORM_PS2) + #define SDL_MAIN_AVAILABLE + + #define SDL_PS2_SKIP_IOP_RESET() \ + void reset_IOP(); \ + void reset_IOP() {} + + #elif defined(SDL_PLATFORM_3DS) + /* + On N3DS, SDL provides a main function that sets up the screens + and storage. + + If you provide this yourself, you may define SDL_MAIN_HANDLED + */ + #define SDL_MAIN_AVAILABLE + + #endif +#endif /* SDL_MAIN_HANDLED */ + + +#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.2.0. + * + * \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 +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ + +#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) +#define main SDL_main +#endif + +#include +#include +#ifdef __cplusplus +extern "C" { +#endif + +/* + * You can (optionally!) define SDL_MAIN_USE_CALLBACKS before including + * SDL_main.h, and then your application will _not_ have a standard + * "main" entry point. Instead, it will operate as a collection of + * functions that are called as necessary by the system. On some + * platforms, this is just a layer where SDL drives your program + * instead of your program driving SDL, on other platforms this might + * hook into the OS to manage the lifecycle. Programs on most platforms + * can use whichever approach they prefer, but the decision boils down + * to: + * + * - Using a standard "main" function: this works like it always has for + * the past 50+ years in C programming, and your app is in control. + * - Using the callback functions: this might clean up some code, + * avoid some #ifdef blocks in your program for some platforms, be more + * resource-friendly to the system, and possibly be the primary way to + * access some future platforms (but none require this at the moment). + * + * This is up to the app; both approaches are considered valid and supported + * ways to write SDL apps. + * + * If using the callbacks, don't define a "main" function. Instead, implement + * the functions listed below in your program. + */ +#ifdef SDL_MAIN_USE_CALLBACKS + +/** + * App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps. + * + * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a + * standard "main" function, you should not supply this. + * + * This function is called by SDL once, at startup. The function should + * initialize whatever is necessary, possibly create windows and open audio + * devices, etc. The `argc` and `argv` parameters work like they would with a + * standard "main" function. + * + * This function should not go into an infinite mainloop; it should do any + * one-time setup it requires and then return. + * + * The app may optionally assign a pointer to `*appstate`. This pointer will + * be provided on every future call to the other entry points, to allow + * application state to be preserved between functions without the app needing + * to use a global variable. If this isn't set, the pointer will be NULL in + * future entry points. + * + * If this function returns SDL_APP_CONTINUE, the app will proceed to normal + * operation, and will begin receiving repeated calls to SDL_AppIterate and + * SDL_AppEvent for the life of the program. If this function returns + * SDL_APP_FAILURE, SDL will call SDL_AppQuit and terminate the process with + * an exit code that reports an error to the platform. If it returns + * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code + * that reports success to the platform. + * + * This function is called by SDL on the main thread. + * + * \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 function is available since SDL 3.2.0. + * + * \sa SDL_AppIterate + * \sa SDL_AppEvent + * \sa SDL_AppQuit + */ +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int argc, char *argv[]); + +/** + * App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps. + * + * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a + * standard "main" function, you should not supply this. + * + * This function is called repeatedly by SDL after SDL_AppInit returns 0. The + * function should operate as a single iteration the program's primary loop; + * it should update whatever state it needs and draw a new frame of video, + * usually. + * + * On some platforms, this function will be called at the refresh rate of the + * display (which might change during the life of your app!). There are no + * promises made about what frequency this function might run at. You should + * use SDL's timer functions if you need to see how much time has passed since + * the last iteration. + * + * There is no need to process the SDL event queue during this function; SDL + * will send events as they arrive in SDL_AppEvent, and in most cases the + * event queue will be empty when this function runs anyhow. + * + * This function should not go into an infinite mainloop; it should do one + * iteration of whatever the program does and return. + * + * The `appstate` parameter is an optional pointer provided by the app during + * SDL_AppInit(). If the app never provided a pointer, this will be NULL. + * + * If this function returns SDL_APP_CONTINUE, the app will continue normal + * operation, receiving repeated calls to SDL_AppIterate and SDL_AppEvent for + * the life of the program. If this function returns SDL_APP_FAILURE, SDL will + * call SDL_AppQuit and terminate the process with an exit code that reports + * an error to the platform. If it returns SDL_APP_SUCCESS, SDL calls + * SDL_AppQuit and terminates with an exit code that reports success to the + * platform. + * + * This function is called by SDL on the main thread. + * + * \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. + * + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + */ +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); + +/** + * App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps. + * + * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a + * standard "main" function, you should not supply this. + * + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. + * + * There is (currently) no guarantee about what thread this will be called + * from; whatever thread pushes an event onto SDL's queue will trigger this + * function. SDL is responsible for pumping the event queue between each call + * to SDL_AppIterate, so in normal operation one should only get events in a + * serial fashion, but be careful if you have a thread that explicitly calls + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. + * + * Events sent to this function are not owned by the app; if you need to save + * the data, you should copy it. + * + * This function should not go into an infinite mainloop; it should handle the + * provided event appropriately and return. + * + * The `appstate` parameter is an optional pointer provided by the app during + * SDL_AppInit(). If the app never provided a pointer, this will be NULL. + * + * If this function returns SDL_APP_CONTINUE, the app will continue normal + * operation, receiving repeated calls to SDL_AppIterate and SDL_AppEvent for + * the life of the program. If this function returns SDL_APP_FAILURE, SDL will + * call SDL_AppQuit and terminate the process with an exit code that reports + * an error to the platform. If it returns SDL_APP_SUCCESS, SDL calls + * SDL_AppQuit and terminates with an exit code that reports success to the + * platform. + * + * \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. + * + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppIterate + */ +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); + +/** + * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. + * + * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a + * standard "main" function, you should not supply this. + * + * This function is called once by SDL before terminating the program. + * + * This function will be called no matter what, even if SDL_AppInit requests + * termination. + * + * This function should not go into an infinite mainloop; it should + * deinitialize any resources necessary, perform whatever shutdown activities, + * and return. + * + * You do not need to call SDL_Quit() in this function, as SDL will call it + * after this function returns and before the process terminates, but it is + * safe to do so. + * + * The `appstate` parameter is an optional pointer provided by the app during + * SDL_AppInit(). If the app never provided a pointer, this will be NULL. This + * function call is the last time this pointer will be provided, so any + * resources to it should be cleaned up here. + * + * This function is called by SDL on the main thread. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AppInit + */ +extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate, SDL_AppResult result); + +#endif /* SDL_MAIN_USE_CALLBACKS */ + + +/** + * The prototype for the application's main() function + * + * \param argc an ANSI-C style main function's argc. + * \param argv an ANSI-C style main function's argv. + * \returns an ANSI-C main return code; generally 0 is considered successful + * program completion, and small non-zero values are considered + * errors. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); + +/** + * An app-supplied function for program entry. + * + * Apps do not directly create this function; they should create a standard + * ANSI-C `main` function instead. If SDL needs to insert some startup code + * before `main` runs, or the platform doesn't actually _use_ a function + * called "main", SDL will do some macro magic to redefine `main` to + * `SDL_main` and provide its own `main`. + * + * Apps should include `SDL_main.h` in the same file as their `main` function, + * and they should not use that symbol for anything else in that file, as it + * might get redefined. + * + * This function is only provided by the app if it isn't using + * SDL_MAIN_USE_CALLBACKS. + * + * Program startup is a surprisingly complex topic. Please see + * [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \param argc an ANSI-C style main function's argc. + * \param argv an ANSI-C style main function's argv. + * \returns an ANSI-C main return code; generally 0 is considered successful + * program completion, and small non-zero values are considered + * errors. + * + * \threadsafety This is the program entry point. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); + +/** + * Circumvent failure of SDL_Init() when not using SDL_main() as an entry + * point. + * + * This function is defined in SDL_main.h, along with the preprocessor rule to + * redefine main() as SDL_main(). Thus to ensure that your main() function + * will not be changed it is necessary to define SDL_MAIN_HANDLED before + * including SDL.h. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); + +/** + * Initializes and launches an SDL application, by doing platform-specific + * initialization before calling your mainFunction and cleanups after it + * returns, if that is needed for a specific platform, otherwise it just calls + * mainFunction. + * + * You can use this if you want to use your own main() implementation without + * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do + * *not* need SDL_SetMainReady(). + * + * \param argc the argc parameter from the application's main() function, or 0 + * if the platform's main-equivalent has no argc. + * \param argv the argv parameter from the application's main() function, or + * NULL if the platform's main-equivalent has no argv. + * \param mainFunction your SDL app's C-style main(). NOT the function you're + * calling this from! Its name doesn't matter; it doesn't + * literally have to be `main`. + * \param reserved should be NULL (reserved for future use, will probably be + * platform-specific then). + * \returns the return value from mainFunction: 0 on success, otherwise + * failure; SDL_GetError() might have more information on the + * failure. + * + * \threadsafety Generally this is called once, near startup, from the + * process's initial thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); + +/** + * An entry point for SDL's use in SDL_MAIN_USE_CALLBACKS. + * + * Generally, you should not call this function directly. This only exists to + * hand off work into SDL as soon as possible, where it has a lot more control + * and functionality available, and make the inline code in SDL_main.h as + * small as possible. + * + * Not all platforms use this, it's actual use is hidden in a magic + * header-only library, and you should not call this directly unless you + * _really_ know what you're doing. + * + * \param argc standard Unix main argc. + * \param argv standard Unix main argv. + * \param appinit the application's SDL_AppInit function. + * \param appiter the application's SDL_AppIterate function. + * \param appevent the application's SDL_AppEvent function. + * \param appquit the application's SDL_AppQuit function. + * \returns standard Unix main return value. + * + * \threadsafety It is not safe to call this anywhere except as the only + * function call in SDL_main. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); + + +#if defined(SDL_PLATFORM_WINDOWS) + +/** + * Register a win32 window class for SDL's use. + * + * This can be called to set the application window class at startup. It is + * safe to call this multiple times, as long as every call is eventually + * paired with a call to SDL_UnregisterApp, but a second registration attempt + * while a previous registration is still active will be ignored, other than + * to increment a counter. + * + * Most applications do not need to, and should not, call this directly; SDL + * will call it when initializing the video subsystem. + * + * \param name the window class name, in UTF-8 encoding. If NULL, SDL + * currently uses "SDL_app" but this isn't guaranteed. + * \param style the value to use in WNDCLASSEX::style. If `name` is NULL, SDL + * currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` regardless of + * what is specified here. + * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL + * will use `GetModuleHandle(NULL)` instead. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); + +/** + * Deregister the win32 window class from an SDL_RegisterApp call. + * + * This can be called to undo the effects of SDL_RegisterApp. + * + * Most applications do not need to, and should not, call this directly; SDL + * will call it when deinitializing the video subsystem. + * + * It is safe to call this multiple times, as long as every call is eventually + * paired with a prior call to SDL_RegisterApp. The window class will only be + * deregistered when the registration counter in SDL_RegisterApp decrements to + * zero through calls to this function. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); + +#endif /* defined(SDL_PLATFORM_WINDOWS) */ + +/** + * Callback from the application to let the suspend continue. + * + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); + +#ifdef __cplusplus +} +#endif + +#include + +#if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) + /* include header-only SDL_main implementations */ + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) + /* platforms which main (-equivalent) can be implemented in plain C */ + #include + #endif +#endif + +#endif /* SDL_main_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main_impl.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main_impl.h new file mode 100644 index 0000000000..14ebb42916 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_main_impl.h @@ -0,0 +1,151 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: Main */ + +#ifndef SDL_main_impl_h_ +#define SDL_main_impl_h_ + +#ifndef SDL_main_h_ +#error "This header should not be included directly, but only via SDL_main.h!" +#endif + +/* if someone wants to include SDL_main.h but doesn't want the main handing magic, + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. + SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, + not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants + to have the SDL_main implementation (from this header) in another source file + than their main() function, for example if SDL_main requires C++ + and main() is implemented in plain C */ +#if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) + + /* the implementations below must be able to use the implement real main(), nothing renamed + (the user's main() will be renamed to SDL_main so it can be called from here) */ + #ifdef main + #undef main + #endif + + #ifdef SDL_MAIN_USE_CALLBACKS + + #if 0 + /* currently there are no platforms that _need_ a magic entry point here + for callbacks, but if one shows up, implement it here. */ + + #else /* use a standard SDL_main, which the app SHOULD NOT ALSO SUPPLY. */ + + /* this define makes the normal SDL_main entry point stuff work...we just provide SDL_main() instead of the app. */ + #define SDL_MAIN_CALLBACK_STANDARD 1 + + int SDL_main(int argc, char **argv) + { + return SDL_EnterAppMainCallbacks(argc, argv, SDL_AppInit, SDL_AppIterate, SDL_AppEvent, SDL_AppQuit); + } + + #endif /* platform-specific tests */ + + #endif /* SDL_MAIN_USE_CALLBACKS */ + + + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) + + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) + + /* these defines/typedefs are needed for the WinMain() definition */ + #ifndef WINAPI + #define WINAPI __stdcall + #endif + + typedef struct HINSTANCE__ * HINSTANCE; + typedef char *LPSTR; + typedef wchar_t *PWSTR; + + /* The VC++ compiler needs main/wmain defined, but not for GDK */ + #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) + + /* This is where execution begins [console apps] */ + #if defined(UNICODE) && UNICODE + int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) + { + (void)argc; + (void)wargv; + (void)wenvp; + return SDL_RunApp(0, NULL, SDL_main, NULL); + } + #else /* ANSI */ + int main(int argc, char *argv[]) + { + (void)argc; + (void)argv; + return SDL_RunApp(0, NULL, SDL_main, NULL); + } + #endif /* UNICODE */ + + #endif /* _MSC_VER && ! SDL_PLATFORM_GDK */ + + /* This is where execution begins [windowed apps and GDK] */ + + #ifdef __cplusplus + extern "C" { + #endif + + #if defined(UNICODE) && UNICODE + int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) + #else /* ANSI */ + int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) + #endif + { + (void)hInst; + (void)hPrev; + (void)szCmdLine; + (void)sw; + return SDL_RunApp(0, NULL, SDL_main, NULL); + } + + #ifdef __cplusplus + } /* extern "C" */ + #endif + + /* end of SDL_PLATFORM_WINDOWS impls */ + + #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ + int main(int argc, char *argv[]) + { + return SDL_RunApp(argc, argv, SDL_main, NULL); + } + + /* end of impls for standard-conforming platforms */ + + #endif /* SDL_PLATFORM_WIN32 etc */ + + #endif /* !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) */ + + /* rename users main() function to SDL_main() so it can be called from the wrappers above */ + #define main SDL_main + +#endif /* SDL_MAIN_HANDLED */ + +#endif /* SDL_main_impl_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_messagebox.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_messagebox.h similarity index 61% rename from code/thirdparty/SDL2-2.32.8/include/SDL_messagebox.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_messagebox.h index 725d4124ad..365ae36a5a 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_messagebox.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_messagebox.h @@ -19,59 +19,87 @@ 3. This notice may not be removed or altered from any source distribution. */ +/** + * # CategoryMessagebox + * + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. + */ + #ifndef SDL_messagebox_h_ #define SDL_messagebox_h_ -#include "SDL_stdinc.h" -#include "SDL_video.h" /* For SDL_Window */ +#include +#include +#include /* For SDL_Window */ -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. + * + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_MessageBoxFlags -{ - SDL_MESSAGEBOX_ERROR = 0x00000010, /**< error dialog */ - SDL_MESSAGEBOX_WARNING = 0x00000020, /**< warning dialog */ - SDL_MESSAGEBOX_INFORMATION = 0x00000040, /**< informational dialog */ - SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT = 0x00000080, /**< buttons placed left to right */ - SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT = 0x00000100 /**< buttons placed right to left */ -} SDL_MessageBoxFlags; +typedef Uint32 SDL_MessageBoxFlags; + +#define SDL_MESSAGEBOX_ERROR 0x00000010u /**< error dialog */ +#define SDL_MESSAGEBOX_WARNING 0x00000020u /**< warning dialog */ +#define SDL_MESSAGEBOX_INFORMATION 0x00000040u /**< informational dialog */ +#define SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT 0x00000080u /**< buttons placed left to right */ +#define SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT 0x00000100u /**< buttons placed right to left */ /** - * Flags for SDL_MessageBoxButtonData. + * SDL_MessageBoxButtonData flags. + * + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_MessageBoxButtonFlags -{ - SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001, /**< Marks the default button when return is hit */ - SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002 /**< Marks the default button when escape is hit */ -} SDL_MessageBoxButtonFlags; +typedef Uint32 SDL_MessageBoxButtonFlags; + +#define SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT 0x00000001u /**< Marks the default button when return is hit */ +#define SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT 0x00000002u /**< Marks the default button when escape is hit */ /** * Individual button data. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { - Uint32 flags; /**< SDL_MessageBoxButtonFlags */ - int buttonid; /**< User defined button id (value returned via SDL_ShowMessageBox) */ - const char * text; /**< The UTF-8 button text */ + SDL_MessageBoxButtonFlags flags; + int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */ + const char *text; /**< The UTF-8 button text */ } SDL_MessageBoxButtonData; /** * RGB value used in a message box color scheme + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { Uint8 r, g, b; } SDL_MessageBoxColor; +/** + * An enumeration of indices inside the colors array of + * SDL_MessageBoxColorScheme. + */ typedef enum SDL_MessageBoxColorType { SDL_MESSAGEBOX_COLOR_BACKGROUND, @@ -79,23 +107,27 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { - Uint32 flags; /**< SDL_MessageBoxFlags */ + SDL_MessageBoxFlags flags; SDL_Window *window; /**< Parent window, can be NULL */ const char *title; /**< UTF-8 title */ const char *message; /**< UTF-8 message text */ @@ -133,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -175,22 +207,20 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message * \param title UTF-8 title text. * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_messagebox_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_metal.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_metal.h similarity index 63% rename from code/thirdparty/SDL2-2.32.8/include/SDL_metal.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_metal.h index d3f21d5ecf..14b1bc87a2 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_metal.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_metal.h @@ -22,16 +22,19 @@ /** * # CategoryMetal * - * Header file for functions to creating Metal layers and views on SDL - * windows. + * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ #define SDL_metal_h_ -#include "SDL_video.h" +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -40,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * This can be cast directly to an NSView or UIView. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -59,12 +62,15 @@ typedef void *SDL_MetalView; * The returned handle can be casted directly to a NSView or UIView. To access * the backing CAMetalLayer, call SDL_Metal_GetLayer(). * - * \since This function is available since SDL 2.0.12. + * \param window the window. + * \returns handle NSView or UIView. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer */ -extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window); +extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *window); /** * Destroy an existing SDL_MetalView object. @@ -72,36 +78,23 @@ extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window); * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was * called after SDL_CreateWindow. * - * \since This function is available since SDL 2.0.12. - * - * \sa SDL_Metal_CreateView - */ -extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); - -/** - * Get a pointer to the backing CAMetalLayer for the given view. + * \param view the SDL_MetalView object. * - * \since This function is available since SDL 2.0.14. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ -extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); +extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); /** - * Get the size of a window's underlying drawable in pixels (for use with - * setting viewport, scissor & etc). - * - * \param window SDL_Window from which the drawable size should be queried. - * \param w Pointer to variable for storing the width in pixels, may be NULL. - * \param h Pointer to variable for storing the height in pixels, may be NULL. + * Get a pointer to the backing CAMetalLayer for the given view. * - * \since This function is available since SDL 2.0.14. + * \param view the SDL_MetalView object. + * \returns a pointer. * - * \sa SDL_GetWindowSize - * \sa SDL_CreateWindow + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w, - int *h); +extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); /* @} *//* Metal support functions */ @@ -109,6 +102,6 @@ extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int * #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_metal_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_misc.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_misc.h similarity index 84% rename from code/thirdparty/SDL2-2.32.8/include/SDL_misc.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_misc.h index 86a82bc5d6..3dd6fcddd6 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_misc.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_misc.h @@ -22,15 +22,16 @@ /** * # CategoryMisc * - * Include file for SDL API functions that don't fit elsewhere. + * SDL API functions that don't fit elsewhere. */ #ifndef SDL_misc_h_ #define SDL_misc_h_ -#include "SDL_stdinc.h" +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -59,21 +60,19 @@ extern "C" { * All this to say: this function can be useful, but you should definitely * test it on every platform you target. * - * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for + * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns 0 on success, or -1 on error; call SDL_GetError() for more + * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 2.0.14. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_misc_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mouse.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mouse.h new file mode 100644 index 0000000000..864135d2be --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mouse.h @@ -0,0 +1,689 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryMouse + * + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. + */ + +#ifndef SDL_mouse_h_ +#define SDL_mouse_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * This is a unique ID for a mouse for the time it is connected to the system, + * and is never reused for the lifetime of the application. + * + * If the mouse is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_MouseID; + +/** + * The structure used to identify an SDL cursor. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Cursor SDL_Cursor; + +/** + * Cursor types for SDL_CreateSystemCursor(). + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_SystemCursor +{ + SDL_SYSTEM_CURSOR_DEFAULT, /**< Default cursor. Usually an arrow. */ + SDL_SYSTEM_CURSOR_TEXT, /**< Text selection. Usually an I-beam. */ + SDL_SYSTEM_CURSOR_WAIT, /**< Wait. Usually an hourglass or watch or spinning ball. */ + SDL_SYSTEM_CURSOR_CROSSHAIR, /**< Crosshair. */ + SDL_SYSTEM_CURSOR_PROGRESS, /**< Program is busy but still interactive. Usually it's WAIT with an arrow. */ + SDL_SYSTEM_CURSOR_NWSE_RESIZE, /**< Double arrow pointing northwest and southeast. */ + SDL_SYSTEM_CURSOR_NESW_RESIZE, /**< Double arrow pointing northeast and southwest. */ + SDL_SYSTEM_CURSOR_EW_RESIZE, /**< Double arrow pointing west and east. */ + SDL_SYSTEM_CURSOR_NS_RESIZE, /**< Double arrow pointing north and south. */ + SDL_SYSTEM_CURSOR_MOVE, /**< Four pointed arrow pointing north, south, east, and west. */ + SDL_SYSTEM_CURSOR_NOT_ALLOWED, /**< Not permitted. Usually a slashed circle or crossbones. */ + SDL_SYSTEM_CURSOR_POINTER, /**< Pointer that indicates a link. Usually a pointing hand. */ + SDL_SYSTEM_CURSOR_NW_RESIZE, /**< Window resize top-left. This may be a single arrow or a double arrow like NWSE_RESIZE. */ + SDL_SYSTEM_CURSOR_N_RESIZE, /**< Window resize top. May be NS_RESIZE. */ + SDL_SYSTEM_CURSOR_NE_RESIZE, /**< Window resize top-right. May be NESW_RESIZE. */ + SDL_SYSTEM_CURSOR_E_RESIZE, /**< Window resize right. May be EW_RESIZE. */ + SDL_SYSTEM_CURSOR_SE_RESIZE, /**< Window resize bottom-right. May be NWSE_RESIZE. */ + SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ + SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ + SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ + SDL_SYSTEM_CURSOR_COUNT +} SDL_SystemCursor; + +/** + * Scroll direction types for the Scroll event + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_MouseWheelDirection +{ + SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */ + SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */ +} SDL_MouseWheelDirection; + +/** + * A bitmask of pressed mouse buttons, as reported by SDL_GetMouseState, etc. + * + * - Button 1: Left mouse button + * - Button 2: Middle mouse button + * - Button 3: Right mouse button + * - Button 4: Side mouse button 1 + * - Button 5: Side mouse button 2 + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState + * \sa SDL_GetRelativeMouseState + */ +typedef Uint32 SDL_MouseButtonFlags; + +#define SDL_BUTTON_LEFT 1 +#define SDL_BUTTON_MIDDLE 2 +#define SDL_BUTTON_RIGHT 3 +#define SDL_BUTTON_X1 4 +#define SDL_BUTTON_X2 5 + +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) + + +/* Function prototypes */ + +/** + * Return whether a mouse is currently connected. + * + * \returns true if a mouse is connected, false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); + +/** + * Get a list of currently connected mice. + * + * Note that this will include any device or virtual driver that includes + * mouse functionality, including some game controllers, KVM switches, etc. + * You should wait for input from a device before you consider it actively in + * use. + * + * \param count a pointer filled in with the number of mice returned, may be + * NULL. + * \returns a 0 terminated array of mouse instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMouseNameForID + * \sa SDL_HasMouse + */ +extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); + +/** + * Get the name of a mouse. + * + * This function returns "" if the mouse doesn't have a name. + * + * \param instance_id the mouse instance ID. + * \returns the name of the selected mouse, or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMice + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID instance_id); + +/** + * Get the window which currently has mouse focus. + * + * \returns the window with mouse focus. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); + +/** + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. + * + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. + * + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. + * + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGlobalMouseState + * \sa SDL_GetRelativeMouseState + */ +extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); + +/** + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. + * + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). + * + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. + * + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. + * + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CaptureMouse + * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState + */ +extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); + +/** + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. + * + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. + * + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. + * + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState + */ +extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); + +/** + * Move the mouse cursor to the given position within the window. + * + * This function generates a mouse motion event if relative mode is not + * enabled. If relative mode is enabled, you can force mouse events for the + * warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint. + * + * Note that this function will appear to succeed, but not actually move the + * mouse when used over Microsoft Remote Desktop. + * + * \param window the window to move the mouse into, or NULL for the current + * mouse focus. + * \param x the x coordinate within the window. + * \param y the y coordinate within the window. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WarpMouseGlobal + */ +extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window *window, + float x, float y); + +/** + * Move the mouse to the given position in global screen space. + * + * This function generates a mouse motion event. + * + * A failure of this function usually means that it is unsupported by a + * platform. + * + * Note that this function will appear to succeed, but not actually move the + * mouse when used over Microsoft Remote Desktop. + * + * \param x the x coordinate. + * \param y the y coordinate. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WarpMouseInWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); + +/** + * Set relative mouse mode for a window. + * + * While the window has focus and relative mouse mode is enabled, the cursor + * is hidden, the mouse position is constrained to the window, and SDL will + * report continuous relative mouse motion even if the mouse is at the edge of + * the window. + * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * + * This function will flush any pending mouse motion for this window. + * + * \param window the window to change. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowRelativeMouseMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); + +/** + * Query whether relative mouse mode is enabled for a window. + * + * \param window the window to query. + * \returns true if relative mode is enabled for a window or false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowRelativeMouseMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); + +/** + * Capture the mouse and to track input outside an SDL window. + * + * Capturing enables your app to obtain mouse events globally, instead of just + * within your window. Not all video targets support this function. When + * capturing is enabled, the current window will get all mouse events, but + * unlike relative mode, no change is made to the cursor and it is not + * restrained to your window. + * + * This function may also deny mouse input to other windows--both those in + * your application and others on the system--so you should use this function + * sparingly, and in small bursts. For example, you might want to track the + * mouse while the user is dragging something, until the user releases a mouse + * button. It is not recommended that you capture the mouse for long periods + * of time, such as the entire time your app is running. For that, you should + * probably use SDL_SetWindowRelativeMouseMode() or SDL_SetWindowMouseGrab(), + * depending on your goals. + * + * While captured, mouse events still report coordinates relative to the + * current (foreground) window, but those coordinates may be outside the + * bounds of the window (including negative values). Capturing is only allowed + * for the foreground window. If the window loses focus while capturing, the + * capture will be disabled automatically. + * + * While capturing is enabled, the current window will have the + * `SDL_WINDOW_MOUSE_CAPTURE` flag set. + * + * Please note that SDL will attempt to "auto capture" the mouse while the + * user is pressing a button; this is to try and make mouse behavior more + * consistent between platforms, and deal with the common case of a user + * dragging the mouse outside of the window. This means that if you are + * calling SDL_CaptureMouse() only to deal with this situation, you do not + * have to (although it is safe to do so). If this causes problems for your + * app, you can disable auto capture by setting the + * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. + * + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGlobalMouseState + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); + +/** + * Create a cursor using the specified bitmap data and mask (in MSB format). + * + * `mask` has to be in MSB (Most Significant Bit) format. + * + * The cursor width (`w`) must be a multiple of 8 bits. + * + * The cursor is created in black and white according to the following: + * + * - data=0, mask=1: white + * - data=1, mask=1: black + * - data=0, mask=0: transparent + * - data=1, mask=0: inverted color if possible, black if not. + * + * Cursors created with this function must be freed with SDL_DestroyCursor(). + * + * If you want to have a color cursor, or create your cursor from an + * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can + * hide the cursor and draw your own as part of your game's rendering, but it + * will be bound to the framerate. + * + * Also, SDL_CreateSystemCursor() is available, which provides several + * readily-available system cursors to pick from. + * + * \param data the color value for each pixel of the cursor. + * \param mask the mask value for each pixel of the cursor. + * \param w the width of the cursor. + * \param h the height of the cursor. + * \param hot_x the x-axis offset from the left of the cursor image to the + * mouse x position, in the range of 0 to `w` - 1. + * \param hot_y the y-axis offset from the top of the cursor image to the + * mouse y position, in the range of 0 to `h` - 1. + * \returns a new cursor with the specified parameters on success or NULL on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateColorCursor + * \sa SDL_CreateSystemCursor + * \sa SDL_DestroyCursor + * \sa SDL_SetCursor + */ +extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 *data, + const Uint8 *mask, + int w, int h, int hot_x, + int hot_y); + +/** + * Create a color cursor. + * + * If this function is passed a surface with alternate representations, the + * surface will be interpreted as the content to be used for 100% display + * scale, and the alternate representations will be used for high DPI + * situations. For example, if the original surface is 32x32, then on a 2x + * macOS display or 200% display scale on Windows, a 64x64 version of the + * image will be used, if available. If a matching version of the image isn't + * available, the closest larger size image will be downscaled to the + * appropriate size and be used instead, if available. Otherwise, the closest + * smaller image will be upscaled and be used instead. + * + * \param surface an SDL_Surface structure representing the cursor image. + * \param hot_x the x position of the cursor hot spot. + * \param hot_y the y position of the cursor hot spot. + * \returns the new cursor on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateCursor + * \sa SDL_CreateSystemCursor + * \sa SDL_DestroyCursor + * \sa SDL_SetCursor + */ +extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, + int hot_x, + int hot_y); + +/** + * Create a system cursor. + * + * \param id an SDL_SystemCursor enum value. + * \returns a cursor on success or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyCursor + */ +extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); + +/** + * Set the active cursor. + * + * This function sets the currently active cursor to the specified one. If the + * cursor is currently visible, the change will be immediately represented on + * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if + * this is desired for any reason. + * + * \param cursor a cursor to make active. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCursor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); + +/** + * Get the active cursor. + * + * This function returns a pointer to the current cursor which is owned by the + * library. It is not necessary to free the cursor with SDL_DestroyCursor(). + * + * \returns the active cursor or NULL if there is no mouse. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetCursor + */ +extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); + +/** + * Get the default cursor. + * + * You do not have to call SDL_DestroyCursor() on the return value, but it is + * safe to do so. + * + * \returns the default cursor on success or NULL on failuree; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); + +/** + * Free a previously-created cursor. + * + * Use this function to free cursor resources created with SDL_CreateCursor(), + * SDL_CreateColorCursor() or SDL_CreateSystemCursor(). + * + * \param cursor the cursor to free. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateColorCursor + * \sa SDL_CreateCursor + * \sa SDL_CreateSystemCursor + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); + +/** + * Show the cursor. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CursorVisible + * \sa SDL_HideCursor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); + +/** + * Hide the cursor. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CursorVisible + * \sa SDL_ShowCursor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); + +/** + * Return whether the cursor is currently being shown. + * + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HideCursor + * \sa SDL_ShowCursor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_mouse_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mutex.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mutex.h new file mode 100644 index 0000000000..c88ec15315 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_mutex.h @@ -0,0 +1,1073 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#ifndef SDL_mutex_h_ +#define SDL_mutex_h_ + +/** + * # CategoryMutex + * + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. + */ + +#include +#include +#include +#include + +#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: + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_NO_THREAD_SAFETY_ANALYSIS \ + SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) + +/******************************************************************************/ + + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \name Mutex functions + */ +/* @{ */ + +/** + * A means to serialize access to a resource between threads. + * + * Mutexes (short for "mutual exclusion") are a synchronization primitive that + * allows exactly one thread to proceed at a time. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Mutex + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Mutex SDL_Mutex; + +/** + * Create a new mutex. + * + * All newly-created mutexes begin in the _unlocked_ state. + * + * Calls to SDL_LockMutex() will not return while the mutex is locked by + * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. + * + * SDL mutexes are reentrant. + * + * \returns the initialized and unlocked mutex or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyMutex + * \sa SDL_LockMutex + * \sa SDL_TryLockMutex + * \sa SDL_UnlockMutex + */ +extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); + +/** + * Lock the mutex. + * + * This will block until the mutex is available, which is to say it is in the + * unlocked state and the OS has chosen the caller as the next thread to lock + * it. Of all threads waiting to lock the mutex, only one may do so at a time. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * This function does not fail; if mutex is NULL, it will return immediately + * having locked nothing. If the mutex is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param mutex the mutex to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryLockMutex + * \sa SDL_UnlockMutex + */ +extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mutex); + +/** + * Try to lock a mutex without blocking. + * + * This works just like SDL_LockMutex(), but if the mutex is not available, + * this function returns false immediately. + * + * This technique is useful if you need exclusive access to a resource but + * don't want to wait for it, and will return to it to try again later. + * + * This function returns true if passed a NULL mutex. + * + * \param mutex the mutex to try to lock. + * \returns true on success, false if the mutex would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockMutex + * \sa SDL_UnlockMutex + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); + +/** + * Unlock the mutex. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * It is illegal to unlock a mutex that has not been locked by the current + * thread, and doing so results in undefined behavior. + * + * \param mutex the mutex to unlock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockMutex + * \sa SDL_TryLockMutex + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(mutex); + +/** + * Destroy a mutex created with SDL_CreateMutex(). + * + * This function must be called on any mutex that is no longer needed. Failure + * to destroy a mutex will result in a system memory or resource leak. While + * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt + * to destroy a locked mutex, and may result in undefined behavior depending + * on the platform. + * + * \param mutex the mutex to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateMutex + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); + +/* @} *//* Mutex functions */ + + +/** + * \name Read/write lock functions + */ +/* @{ */ + +/** + * A mutex that allows read-only threads to run in parallel. + * + * A rwlock is roughly the same concept as SDL_Mutex, but allows threads that + * request read-only access to all hold the lock at the same time. If a thread + * requests write access, it will block until all read-only threads have + * released the lock, and no one else can hold the thread (for reading or + * writing) at the same time as the writing thread. + * + * This can be more efficient in cases where several threads need to access + * data frequently, but changes to that data are rare. + * + * There are other rules that apply to rwlocks that don't apply to mutexes, + * about how threads are scheduled and when they can be recursively locked. + * These are documented in the other rwlock functions. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RWLock SDL_RWLock; + +/** + * Create a new read/write lock. + * + * A read/write lock is useful for situations where you have multiple threads + * trying to access a resource that is rarely updated. All threads requesting + * a read-only lock will be allowed to run in parallel; if a thread requests a + * write lock, it will be provided exclusive access. This makes it safe for + * multiple threads to use a resource at the same time if they promise not to + * change it, and when it has to be changed, the rwlock will serve as a + * gateway to make sure those changes can be made safely. + * + * In the right situation, a rwlock can be more efficient than a mutex, which + * only lets a single thread proceed at a time, even if it won't be modifying + * the data. + * + * All newly-created read/write locks begin in the _unlocked_ state. + * + * Calls to SDL_LockRWLockForReading() and SDL_LockRWLockForWriting will not + * return while the rwlock is locked _for writing_ by another thread. See + * SDL_TryLockRWLockForReading() and SDL_TryLockRWLockForWriting() to attempt + * to lock without blocking. + * + * SDL read/write locks are only recursive for read-only locks! They are not + * guaranteed to be fair, or provide access in a FIFO manner! They are not + * guaranteed to favor writers. You may not lock a rwlock for both read-only + * and write access at the same time from the same thread (so you can't + * promote your read-only lock to a write lock without unlocking first). + * + * \returns the initialized and unlocked read/write lock or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyRWLock + * \sa SDL_LockRWLockForReading + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); + +/** + * Lock the read/write lock for _read only_ operations. + * + * This will block until the rwlock is available, which is to say it is not + * locked for writing by any other thread. Of all threads waiting to lock the + * rwlock, all may do so at the same time as long as they are requesting + * read-only access; if a thread wants to lock for writing, only one may do so + * at a time, and no other threads, read-only or not, may hold the lock at the + * same time. + * + * It is legal for the owning thread to lock an already-locked rwlock for + * reading. It must unlock it the same number of times before it is actually + * made available for other threads in the system (this is known as a + * "recursive rwlock"). + * + * Note that locking for writing is not recursive (this is only available to + * read-only locks). + * + * It is illegal to request a read-only lock from a thread that already holds + * the write lock. Doing so results in undefined behavior. Unlock the write + * lock before requesting a read-only lock. (But, of course, if you have the + * write lock, you don't need further locks to read in any case.) + * + * This function does not fail; if rwlock is NULL, it will return immediately + * having locked nothing. If the rwlock is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param rwlock the read/write lock to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_UnlockRWLock + */ +extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SDL_ACQUIRE_SHARED(rwlock); + +/** + * Lock the read/write lock for _write_ operations. + * + * This will block until the rwlock is available, which is to say it is not + * locked for reading or writing by any other thread. Only one thread may hold + * the lock when it requests write access; all other threads, whether they + * also want to write or only want read-only access, must wait until the + * writer thread has released the lock. + * + * It is illegal for the owning thread to lock an already-locked rwlock for + * writing (read-only may be locked recursively, writing can not). Doing so + * results in undefined behavior. + * + * It is illegal to request a write lock from a thread that already holds a + * read-only lock. Doing so results in undefined behavior. Unlock the + * read-only lock before requesting a write lock. + * + * This function does not fail; if rwlock is NULL, it will return immediately + * having locked nothing. If the rwlock is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param rwlock the read/write lock to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SDL_ACQUIRE(rwlock); + +/** + * Try to lock a read/write lock _for reading_ without blocking. + * + * This works just like SDL_LockRWLockForReading(), but if the rwlock is not + * available, then this function returns false immediately. + * + * This technique is useful if you need access to a resource but don't want to + * wait for it, and will return to it to try again later. + * + * Trying to lock for read-only access can succeed if other threads are + * holding read-only locks, as this won't prevent access. + * + * This function returns true if passed a NULL rwlock. + * + * \param rwlock the rwlock to try to lock. + * \returns true on success, false if the lock would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); + +/** + * Try to lock a read/write lock _for writing_ without blocking. + * + * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not + * available, then this function returns false immediately. + * + * This technique is useful if you need exclusive access to a resource but + * don't want to wait for it, and will return to it to try again later. + * + * It is illegal for the owning thread to lock an already-locked rwlock for + * writing (read-only may be locked recursively, writing can not). Doing so + * results in undefined behavior. + * + * It is illegal to request a write lock from a thread that already holds a + * read-only lock. Doing so results in undefined behavior. Unlock the + * read-only lock before requesting a write lock. + * + * This function returns true if passed a NULL rwlock. + * + * \param rwlock the rwlock to try to lock. + * \returns true on success, false if the lock would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_UnlockRWLock + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); + +/** + * Unlock the read/write lock. + * + * Use this function to unlock the rwlock, whether it was locked for read-only + * or write operations. + * + * It is legal for the owning thread to lock an already-locked read-only lock. + * It must unlock it the same number of times before it is actually made + * available for other threads in the system (this is known as a "recursive + * rwlock"). + * + * It is illegal to unlock a rwlock that has not been locked by the current + * thread, and doing so results in undefined behavior. + * + * \param rwlock the rwlock to unlock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEASE_GENERIC(rwlock); + +/** + * Destroy a read/write lock created with SDL_CreateRWLock(). + * + * This function must be called on any read/write lock that is no longer + * needed. Failure to destroy a rwlock will result in a system memory or + * resource leak. While it is safe to destroy a rwlock that is _unlocked_, it + * is not safe to attempt to destroy a locked rwlock, and may result in + * undefined behavior depending on the platform. + * + * \param rwlock the rwlock to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRWLock + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); + +/* @} *//* Read/write lock functions */ + + +/** + * \name Semaphore functions + */ +/* @{ */ + +/** + * A means to manage access to a resource, by count, between threads. + * + * Semaphores (specifically, "counting semaphores"), let X number of threads + * request access at the same time, each thread granted access decrementing a + * counter. When the counter reaches zero, future requests block until a prior + * thread releases their request, incrementing the counter again. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Semaphore_(programming) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Semaphore SDL_Semaphore; + +/** + * Create a semaphore. + * + * This function creates a new semaphore and initializes it with the value + * `initial_value`. Each wait operation on the semaphore will atomically + * decrement the semaphore value and potentially block if the semaphore value + * is 0. Each post operation will atomically increment the semaphore value and + * wake waiting threads and allow them to retry the wait operation. + * + * \param initial_value the starting value of the semaphore. + * \returns a new semaphore or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySemaphore + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_GetSemaphoreValue + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_value); + +/** + * Destroy a semaphore. + * + * It is not safe to destroy a semaphore if there are threads currently + * waiting on it. + * + * \param sem the semaphore to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateSemaphore + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); + +/** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until the semaphore pointed to by + * `sem` has a positive value, and then atomically decrement the semaphore + * value. + * + * This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with + * a time length of -1. + * + * \param sem the semaphore wait on. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); + +/** + * See if a semaphore has a positive value and decrement it if it does. + * + * This function checks to see if the semaphore pointed to by `sem` has a + * positive value and atomically decrements the semaphore value if it does. If + * the semaphore doesn't have a positive value, the function immediately + * returns false. + * + * \param sem the semaphore to wait on. + * \returns true if the wait succeeds, false if the wait would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); + +/** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until either the semaphore + * pointed to by `sem` has a positive value or the specified time has elapsed. + * If the call is successful it will atomically decrement the semaphore value. + * + * \param sem the semaphore to wait on. + * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if the wait succeeds or false if the wait times out. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphore + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); + +/** + * Atomically increment a semaphore's value and wake waiting threads. + * + * \param sem the semaphore to increment. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); + +/** + * Get the current value of a semaphore. + * + * \param sem the semaphore to query. + * \returns the current value of the semaphore. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); + +/* @} *//* Semaphore functions */ + + +/** + * \name Condition variable functions + */ +/* @{ */ + +/** + * A means to block multiple threads until a condition is satisfied. + * + * Condition variables, paired with an SDL_Mutex, let an app halt multiple + * threads until a condition has occurred, at which time the app can release + * one or all waiting threads. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Condition_variable + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Condition SDL_Condition; + +/** + * Create a condition variable. + * + * \returns a new condition variable or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BroadcastCondition + * \sa SDL_SignalCondition + * \sa SDL_WaitCondition + * \sa SDL_WaitConditionTimeout + * \sa SDL_DestroyCondition + */ +extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); + +/** + * Destroy a condition variable. + * + * \param cond the condition variable to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateCondition + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); + +/** + * Restart one of the threads that are waiting on the condition variable. + * + * \param cond the condition variable to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BroadcastCondition + * \sa SDL_WaitCondition + * \sa SDL_WaitConditionTimeout + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); + +/** + * Restart all threads that are waiting on the condition variable. + * + * \param cond the condition variable to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalCondition + * \sa SDL_WaitCondition + * \sa SDL_WaitConditionTimeout + */ +extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); + +/** + * Wait until a condition variable is signaled. + * + * This function unlocks the specified `mutex` and waits for another thread to + * call SDL_SignalCondition() or SDL_BroadcastCondition() on the condition + * variable `cond`. Once the condition variable is signaled, the mutex is + * re-locked and the function returns. + * + * The mutex must be locked before calling this function. Locking the mutex + * recursively (more than once) is not supported and leads to undefined + * behavior. + * + * This function is the equivalent of calling SDL_WaitConditionTimeout() with + * a time length of -1. + * + * \param cond the condition variable to wait on. + * \param mutex the mutex used to coordinate thread access. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BroadcastCondition + * \sa SDL_SignalCondition + * \sa SDL_WaitConditionTimeout + */ +extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex *mutex); + +/** + * Wait until a condition variable is signaled or a certain time has passed. + * + * This function unlocks the specified `mutex` and waits for another thread to + * call SDL_SignalCondition() or SDL_BroadcastCondition() on the condition + * variable `cond`, or for the specified time to elapse. Once the condition + * variable is signaled or the time elapsed, the mutex is re-locked and the + * function returns. + * + * The mutex must be locked before calling this function. Locking the mutex + * recursively (more than once) is not supported and leads to undefined + * behavior. + * + * \param cond the condition variable to wait on. + * \param mutex the mutex used to coordinate thread access. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BroadcastCondition + * \sa SDL_SignalCondition + * \sa SDL_WaitCondition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, + SDL_Mutex *mutex, Sint32 timeoutMS); + +/* @} *//* Condition variable functions */ + +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_mutex_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_oldnames.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_oldnames.h new file mode 100644 index 0000000000..c93607e3f4 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_oldnames.h @@ -0,0 +1,1327 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* + * Definitions to ease transition from SDL2 code + */ + +#ifndef SDL_oldnames_h_ +#define SDL_oldnames_h_ + +#include + +/* The new function names are recommended, but if you want to have the + * old names available while you are in the process of migrating code + * to SDL3, you can define `SDL_ENABLE_OLD_NAMES` in your project. + * + * You can use https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_symbols.py to mass rename the symbols defined here in your codebase: + * rename_symbols.py --all-symbols source_code_path + */ +#ifdef SDL_ENABLE_OLD_NAMES + +/* ##SDL_atomic.h */ +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer +#define SDL_AtomicLock SDL_LockSpinlock +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer +#define SDL_AtomicTryLock SDL_TryLockSpinlock +#define SDL_AtomicUnlock SDL_UnlockSpinlock +#define SDL_atomic_t SDL_AtomicInt + +/* ##SDL_audio.h */ +#define AUDIO_F32 SDL_AUDIO_F32LE +#define AUDIO_F32LSB SDL_AUDIO_F32LE +#define AUDIO_F32MSB SDL_AUDIO_F32BE +#define AUDIO_F32SYS SDL_AUDIO_F32 +#define AUDIO_S16 SDL_AUDIO_S16LE +#define AUDIO_S16LSB SDL_AUDIO_S16LE +#define AUDIO_S16MSB SDL_AUDIO_S16BE +#define AUDIO_S16SYS SDL_AUDIO_S16 +#define AUDIO_S32 SDL_AUDIO_S32LE +#define AUDIO_S32LSB SDL_AUDIO_S32LE +#define AUDIO_S32MSB SDL_AUDIO_S32BE +#define AUDIO_S32SYS SDL_AUDIO_S32 +#define AUDIO_S8 SDL_AUDIO_S8 +#define AUDIO_U8 SDL_AUDIO_U8 +#define SDL_AudioStreamAvailable SDL_GetAudioStreamAvailable +#define SDL_AudioStreamClear SDL_ClearAudioStream +#define SDL_AudioStreamFlush SDL_FlushAudioStream +#define SDL_AudioStreamGet SDL_GetAudioStreamData +#define SDL_AudioStreamPut SDL_PutAudioStreamData +#define SDL_FreeAudioStream SDL_DestroyAudioStream +#define SDL_FreeWAV SDL_free +#define SDL_LoadWAV_RW SDL_LoadWAV_IO +#define SDL_MixAudioFormat SDL_MixAudio +#define SDL_NewAudioStream SDL_CreateAudioStream + +/* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores +#define SDL_SIMDGetAlignment SDL_GetSIMDAlignment + +/* ##SDL_endian.h */ +#define SDL_SwapBE16 SDL_Swap16BE +#define SDL_SwapBE32 SDL_Swap32BE +#define SDL_SwapBE64 SDL_Swap64BE +#define SDL_SwapLE16 SDL_Swap16LE +#define SDL_SwapLE32 SDL_Swap32LE +#define SDL_SwapLE64 SDL_Swap64LE + +/* ##SDL_events.h */ +#define SDL_APP_DIDENTERBACKGROUND SDL_EVENT_DID_ENTER_BACKGROUND +#define SDL_APP_DIDENTERFOREGROUND SDL_EVENT_DID_ENTER_FOREGROUND +#define SDL_APP_LOWMEMORY SDL_EVENT_LOW_MEMORY +#define SDL_APP_TERMINATING SDL_EVENT_TERMINATING +#define SDL_APP_WILLENTERBACKGROUND SDL_EVENT_WILL_ENTER_BACKGROUND +#define SDL_APP_WILLENTERFOREGROUND SDL_EVENT_WILL_ENTER_FOREGROUND +#define SDL_AUDIODEVICEADDED SDL_EVENT_AUDIO_DEVICE_ADDED +#define SDL_AUDIODEVICEREMOVED SDL_EVENT_AUDIO_DEVICE_REMOVED +#define SDL_CLIPBOARDUPDATE SDL_EVENT_CLIPBOARD_UPDATE +#define SDL_CONTROLLERAXISMOTION SDL_EVENT_GAMEPAD_AXIS_MOTION +#define SDL_CONTROLLERBUTTONDOWN SDL_EVENT_GAMEPAD_BUTTON_DOWN +#define SDL_CONTROLLERBUTTONUP SDL_EVENT_GAMEPAD_BUTTON_UP +#define SDL_CONTROLLERDEVICEADDED SDL_EVENT_GAMEPAD_ADDED +#define SDL_CONTROLLERDEVICEREMAPPED SDL_EVENT_GAMEPAD_REMAPPED +#define SDL_CONTROLLERDEVICEREMOVED SDL_EVENT_GAMEPAD_REMOVED +#define SDL_CONTROLLERSENSORUPDATE SDL_EVENT_GAMEPAD_SENSOR_UPDATE +#define SDL_CONTROLLERSTEAMHANDLEUPDATED SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED +#define SDL_CONTROLLERTOUCHPADDOWN SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN +#define SDL_CONTROLLERTOUCHPADMOTION SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION +#define SDL_CONTROLLERTOUCHPADUP SDL_EVENT_GAMEPAD_TOUCHPAD_UP +#define SDL_ControllerAxisEvent SDL_GamepadAxisEvent +#define SDL_ControllerButtonEvent SDL_GamepadButtonEvent +#define SDL_ControllerDeviceEvent SDL_GamepadDeviceEvent +#define SDL_ControllerSensorEvent SDL_GamepadSensorEvent +#define SDL_ControllerTouchpadEvent SDL_GamepadTouchpadEvent +#define SDL_DISPLAYEVENT_CONNECTED SDL_EVENT_DISPLAY_ADDED +#define SDL_DISPLAYEVENT_DISCONNECTED SDL_EVENT_DISPLAY_REMOVED +#define SDL_DISPLAYEVENT_MOVED SDL_EVENT_DISPLAY_MOVED +#define SDL_DISPLAYEVENT_ORIENTATION SDL_EVENT_DISPLAY_ORIENTATION +#define SDL_DROPBEGIN SDL_EVENT_DROP_BEGIN +#define SDL_DROPCOMPLETE SDL_EVENT_DROP_COMPLETE +#define SDL_DROPFILE SDL_EVENT_DROP_FILE +#define SDL_DROPTEXT SDL_EVENT_DROP_TEXT +#define SDL_DelEventWatch SDL_RemoveEventWatch +#define SDL_FINGERDOWN SDL_EVENT_FINGER_DOWN +#define SDL_FINGERMOTION SDL_EVENT_FINGER_MOTION +#define SDL_FINGERUP SDL_EVENT_FINGER_UP +#define SDL_FIRSTEVENT SDL_EVENT_FIRST +#define SDL_JOYAXISMOTION SDL_EVENT_JOYSTICK_AXIS_MOTION +#define SDL_JOYBATTERYUPDATED SDL_EVENT_JOYSTICK_BATTERY_UPDATED +#define SDL_JOYBUTTONDOWN SDL_EVENT_JOYSTICK_BUTTON_DOWN +#define SDL_JOYBUTTONUP SDL_EVENT_JOYSTICK_BUTTON_UP +#define SDL_JOYDEVICEADDED SDL_EVENT_JOYSTICK_ADDED +#define SDL_JOYDEVICEREMOVED SDL_EVENT_JOYSTICK_REMOVED +#define SDL_JOYBALLMOTION SDL_EVENT_JOYSTICK_BALL_MOTION +#define SDL_JOYHATMOTION SDL_EVENT_JOYSTICK_HAT_MOTION +#define SDL_KEYDOWN SDL_EVENT_KEY_DOWN +#define SDL_KEYMAPCHANGED SDL_EVENT_KEYMAP_CHANGED +#define SDL_KEYUP SDL_EVENT_KEY_UP +#define SDL_LASTEVENT SDL_EVENT_LAST +#define SDL_LOCALECHANGED SDL_EVENT_LOCALE_CHANGED +#define SDL_MOUSEBUTTONDOWN SDL_EVENT_MOUSE_BUTTON_DOWN +#define SDL_MOUSEBUTTONUP SDL_EVENT_MOUSE_BUTTON_UP +#define SDL_MOUSEMOTION SDL_EVENT_MOUSE_MOTION +#define SDL_MOUSEWHEEL SDL_EVENT_MOUSE_WHEEL +#define SDL_POLLSENTINEL SDL_EVENT_POLL_SENTINEL +#define SDL_QUIT SDL_EVENT_QUIT +#define SDL_RENDER_DEVICE_RESET SDL_EVENT_RENDER_DEVICE_RESET +#define SDL_RENDER_TARGETS_RESET SDL_EVENT_RENDER_TARGETS_RESET +#define SDL_SENSORUPDATE SDL_EVENT_SENSOR_UPDATE +#define SDL_TEXTEDITING SDL_EVENT_TEXT_EDITING +#define SDL_TEXTEDITING_EXT SDL_EVENT_TEXT_EDITING_EXT +#define SDL_TEXTINPUT SDL_EVENT_TEXT_INPUT +#define SDL_USEREVENT SDL_EVENT_USER +#define SDL_WINDOWEVENT_CLOSE SDL_EVENT_WINDOW_CLOSE_REQUESTED +#define SDL_WINDOWEVENT_DISPLAY_CHANGED SDL_EVENT_WINDOW_DISPLAY_CHANGED +#define SDL_WINDOWEVENT_ENTER SDL_EVENT_WINDOW_MOUSE_ENTER +#define SDL_WINDOWEVENT_EXPOSED SDL_EVENT_WINDOW_EXPOSED +#define SDL_WINDOWEVENT_FOCUS_GAINED SDL_EVENT_WINDOW_FOCUS_GAINED +#define SDL_WINDOWEVENT_FOCUS_LOST SDL_EVENT_WINDOW_FOCUS_LOST +#define SDL_WINDOWEVENT_HIDDEN SDL_EVENT_WINDOW_HIDDEN +#define SDL_WINDOWEVENT_HIT_TEST SDL_EVENT_WINDOW_HIT_TEST +#define SDL_WINDOWEVENT_ICCPROF_CHANGED SDL_EVENT_WINDOW_ICCPROF_CHANGED +#define SDL_WINDOWEVENT_LEAVE SDL_EVENT_WINDOW_MOUSE_LEAVE +#define SDL_WINDOWEVENT_MAXIMIZED SDL_EVENT_WINDOW_MAXIMIZED +#define SDL_WINDOWEVENT_MINIMIZED SDL_EVENT_WINDOW_MINIMIZED +#define SDL_WINDOWEVENT_MOVED SDL_EVENT_WINDOW_MOVED +#define SDL_WINDOWEVENT_RESIZED SDL_EVENT_WINDOW_RESIZED +#define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED +#define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN +#define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED +#define SDL_eventaction SDL_EventAction + +/* ##SDL_gamecontroller.h */ +#define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID +#define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX +#define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT +#define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX +#define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY +#define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER +#define SDL_CONTROLLER_AXIS_TRIGGERRIGHT SDL_GAMEPAD_AXIS_RIGHT_TRIGGER +#define SDL_CONTROLLER_BINDTYPE_AXIS SDL_GAMEPAD_BINDTYPE_AXIS +#define SDL_CONTROLLER_BINDTYPE_BUTTON SDL_GAMEPAD_BINDTYPE_BUTTON +#define SDL_CONTROLLER_BINDTYPE_HAT SDL_GAMEPAD_BINDTYPE_HAT +#define SDL_CONTROLLER_BINDTYPE_NONE SDL_GAMEPAD_BINDTYPE_NONE +#define SDL_CONTROLLER_BUTTON_A SDL_GAMEPAD_BUTTON_SOUTH +#define SDL_CONTROLLER_BUTTON_B SDL_GAMEPAD_BUTTON_EAST +#define SDL_CONTROLLER_BUTTON_BACK SDL_GAMEPAD_BUTTON_BACK +#define SDL_CONTROLLER_BUTTON_DPAD_DOWN SDL_GAMEPAD_BUTTON_DPAD_DOWN +#define SDL_CONTROLLER_BUTTON_DPAD_LEFT SDL_GAMEPAD_BUTTON_DPAD_LEFT +#define SDL_CONTROLLER_BUTTON_DPAD_RIGHT SDL_GAMEPAD_BUTTON_DPAD_RIGHT +#define SDL_CONTROLLER_BUTTON_DPAD_UP SDL_GAMEPAD_BUTTON_DPAD_UP +#define SDL_CONTROLLER_BUTTON_GUIDE SDL_GAMEPAD_BUTTON_GUIDE +#define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID +#define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER +#define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT +#define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 +#define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 +#define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 +#define SDL_CONTROLLER_BUTTON_PADDLE3 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2 +#define SDL_CONTROLLER_BUTTON_PADDLE4 SDL_GAMEPAD_BUTTON_LEFT_PADDLE2 +#define SDL_CONTROLLER_BUTTON_RIGHTSHOULDER SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER +#define SDL_CONTROLLER_BUTTON_RIGHTSTICK SDL_GAMEPAD_BUTTON_RIGHT_STICK +#define SDL_CONTROLLER_BUTTON_START SDL_GAMEPAD_BUTTON_START +#define SDL_CONTROLLER_BUTTON_TOUCHPAD SDL_GAMEPAD_BUTTON_TOUCHPAD +#define SDL_CONTROLLER_BUTTON_X SDL_GAMEPAD_BUTTON_WEST +#define SDL_CONTROLLER_BUTTON_Y SDL_GAMEPAD_BUTTON_NORTH +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO +#define SDL_CONTROLLER_TYPE_PS3 SDL_GAMEPAD_TYPE_PS3 +#define SDL_CONTROLLER_TYPE_PS4 SDL_GAMEPAD_TYPE_PS4 +#define SDL_CONTROLLER_TYPE_PS5 SDL_GAMEPAD_TYPE_PS5 +#define SDL_CONTROLLER_TYPE_UNKNOWN SDL_GAMEPAD_TYPE_STANDARD +#define SDL_CONTROLLER_TYPE_VIRTUAL SDL_GAMEPAD_TYPE_VIRTUAL +#define SDL_CONTROLLER_TYPE_XBOX360 SDL_GAMEPAD_TYPE_XBOX360 +#define SDL_CONTROLLER_TYPE_XBOXONE SDL_GAMEPAD_TYPE_XBOXONE +#define SDL_GameController SDL_Gamepad +#define SDL_GameControllerAddMapping SDL_AddGamepadMapping +#define SDL_GameControllerAddMappingsFromFile SDL_AddGamepadMappingsFromFile +#define SDL_GameControllerAddMappingsFromRW SDL_AddGamepadMappingsFromIO +#define SDL_GameControllerAxis SDL_GamepadAxis +#define SDL_GameControllerBindType SDL_GamepadBindingType +#define SDL_GameControllerButton SDL_GamepadButton +#define SDL_GameControllerClose SDL_CloseGamepad +#define SDL_GameControllerFromInstanceID SDL_GetGamepadFromID +#define SDL_GameControllerFromPlayerIndex SDL_GetGamepadFromPlayerIndex +#define SDL_GameControllerGetAppleSFSymbolsNameForAxis SDL_GetGamepadAppleSFSymbolsNameForAxis +#define SDL_GameControllerGetAppleSFSymbolsNameForButton SDL_GetGamepadAppleSFSymbolsNameForButton +#define SDL_GameControllerGetAttached SDL_GamepadConnected +#define SDL_GameControllerGetAxis SDL_GetGamepadAxis +#define SDL_GameControllerGetAxisFromString SDL_GetGamepadAxisFromString +#define SDL_GameControllerGetButton SDL_GetGamepadButton +#define SDL_GameControllerGetButtonFromString SDL_GetGamepadButtonFromString +#define SDL_GameControllerGetFirmwareVersion SDL_GetGamepadFirmwareVersion +#define SDL_GameControllerGetJoystick SDL_GetGamepadJoystick +#define SDL_GameControllerGetNumTouchpadFingers SDL_GetNumGamepadTouchpadFingers +#define SDL_GameControllerGetNumTouchpads SDL_GetNumGamepadTouchpads +#define SDL_GameControllerGetPlayerIndex SDL_GetGamepadPlayerIndex +#define SDL_GameControllerGetProduct SDL_GetGamepadProduct +#define SDL_GameControllerGetProductVersion SDL_GetGamepadProductVersion +#define SDL_GameControllerGetSensorData SDL_GetGamepadSensorData +#define SDL_GameControllerGetSensorDataRate SDL_GetGamepadSensorDataRate +#define SDL_GameControllerGetSerial SDL_GetGamepadSerial +#define SDL_GameControllerGetSteamHandle SDL_GetGamepadSteamHandle +#define SDL_GameControllerGetStringForAxis SDL_GetGamepadStringForAxis +#define SDL_GameControllerGetStringForButton SDL_GetGamepadStringForButton +#define SDL_GameControllerGetTouchpadFinger SDL_GetGamepadTouchpadFinger +#define SDL_GameControllerGetType SDL_GetGamepadType +#define SDL_GameControllerGetVendor SDL_GetGamepadVendor +#define SDL_GameControllerHasAxis SDL_GamepadHasAxis +#define SDL_GameControllerHasButton SDL_GamepadHasButton +#define SDL_GameControllerHasSensor SDL_GamepadHasSensor +#define SDL_GameControllerIsSensorEnabled SDL_GamepadSensorEnabled +#define SDL_GameControllerMapping SDL_GetGamepadMapping +#define SDL_GameControllerMappingForGUID SDL_GetGamepadMappingForGUID +#define SDL_GameControllerName SDL_GetGamepadName +#define SDL_GameControllerOpen SDL_OpenGamepad +#define SDL_GameControllerPath SDL_GetGamepadPath +#define SDL_GameControllerRumble SDL_RumbleGamepad +#define SDL_GameControllerRumbleTriggers SDL_RumbleGamepadTriggers +#define SDL_GameControllerSendEffect SDL_SendGamepadEffect +#define SDL_GameControllerSetLED SDL_SetGamepadLED +#define SDL_GameControllerSetPlayerIndex SDL_SetGamepadPlayerIndex +#define SDL_GameControllerSetSensorEnabled SDL_SetGamepadSensorEnabled +#define SDL_GameControllerType SDL_GamepadType +#define SDL_GameControllerUpdate SDL_UpdateGamepads +#define SDL_INIT_GAMECONTROLLER SDL_INIT_GAMEPAD +#define SDL_IsGameController SDL_IsGamepad + +/* ##SDL_guid.h */ +#define SDL_GUIDFromString SDL_StringToGUID + +/* ##SDL_haptic.h */ +#define SDL_HapticClose SDL_CloseHaptic +#define SDL_HapticDestroyEffect SDL_DestroyHapticEffect +#define SDL_HapticGetEffectStatus SDL_GetHapticEffectStatus +#define SDL_HapticNewEffect SDL_CreateHapticEffect +#define SDL_HapticNumAxes SDL_GetNumHapticAxes +#define SDL_HapticNumEffects SDL_GetMaxHapticEffects +#define SDL_HapticNumEffectsPlaying SDL_GetMaxHapticEffectsPlaying +#define SDL_HapticOpen SDL_OpenHaptic +#define SDL_HapticOpenFromJoystick SDL_OpenHapticFromJoystick +#define SDL_HapticOpenFromMouse SDL_OpenHapticFromMouse +#define SDL_HapticPause SDL_PauseHaptic +#define SDL_HapticQuery SDL_GetHapticFeatures +#define SDL_HapticRumbleInit SDL_InitHapticRumble +#define SDL_HapticRumblePlay SDL_PlayHapticRumble +#define SDL_HapticRumbleStop SDL_StopHapticRumble +#define SDL_HapticRunEffect SDL_RunHapticEffect +#define SDL_HapticSetAutocenter SDL_SetHapticAutocenter +#define SDL_HapticSetGain SDL_SetHapticGain +#define SDL_HapticStopAll SDL_StopHapticEffects +#define SDL_HapticStopEffect SDL_StopHapticEffect +#define SDL_HapticUnpause SDL_ResumeHaptic +#define SDL_HapticUpdateEffect SDL_UpdateHapticEffect +#define SDL_JoystickIsHaptic SDL_IsJoystickHaptic +#define SDL_MouseIsHaptic SDL_IsMouseHaptic + +/* ##SDL_hints.h */ +#define SDL_DelHintCallback SDL_RemoveHintCallback +#define SDL_HINT_ALLOW_TOPMOST SDL_HINT_WINDOW_ALLOW_TOPMOST +#define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT +#define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT +#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS +#define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES +#define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC +#define SDL_HINT_LINUX_JOYSTICK_DEADZONES SDL_HINT_JOYSTICK_LINUX_DEADZONES + +/* ##SDL_joystick.h */ +#define SDL_JOYSTICK_TYPE_GAMECONTROLLER SDL_JOYSTICK_TYPE_GAMEPAD +#define SDL_JoystickAttachVirtualEx SDL_AttachVirtualJoystick +#define SDL_JoystickClose SDL_CloseJoystick +#define SDL_JoystickDetachVirtual SDL_DetachVirtualJoystick +#define SDL_JoystickFromInstanceID SDL_GetJoystickFromID +#define SDL_JoystickFromPlayerIndex SDL_GetJoystickFromPlayerIndex +#define SDL_JoystickGUID SDL_GUID +#define SDL_JoystickGetAttached SDL_JoystickConnected +#define SDL_JoystickGetAxis SDL_GetJoystickAxis +#define SDL_JoystickGetAxisInitialState SDL_GetJoystickAxisInitialState +#define SDL_JoystickGetBall SDL_GetJoystickBall +#define SDL_JoystickGetButton SDL_GetJoystickButton +#define SDL_JoystickGetFirmwareVersion SDL_GetJoystickFirmwareVersion +#define SDL_JoystickGetGUID SDL_GetJoystickGUID +#define SDL_JoystickGetGUIDFromString SDL_StringToGUID +#define SDL_JoystickGetHat SDL_GetJoystickHat +#define SDL_JoystickGetPlayerIndex SDL_GetJoystickPlayerIndex +#define SDL_JoystickGetProduct SDL_GetJoystickProduct +#define SDL_JoystickGetProductVersion SDL_GetJoystickProductVersion +#define SDL_JoystickGetSerial SDL_GetJoystickSerial +#define SDL_JoystickGetType SDL_GetJoystickType +#define SDL_JoystickGetVendor SDL_GetJoystickVendor +#define SDL_JoystickInstanceID SDL_GetJoystickID +#define SDL_JoystickIsVirtual SDL_IsJoystickVirtual +#define SDL_JoystickName SDL_GetJoystickName +#define SDL_JoystickNumAxes SDL_GetNumJoystickAxes +#define SDL_JoystickNumBalls SDL_GetNumJoystickBalls +#define SDL_JoystickNumButtons SDL_GetNumJoystickButtons +#define SDL_JoystickNumHats SDL_GetNumJoystickHats +#define SDL_JoystickOpen SDL_OpenJoystick +#define SDL_JoystickPath SDL_GetJoystickPath +#define SDL_JoystickRumble SDL_RumbleJoystick +#define SDL_JoystickRumbleTriggers SDL_RumbleJoystickTriggers +#define SDL_JoystickSendEffect SDL_SendJoystickEffect +#define SDL_JoystickSetLED SDL_SetJoystickLED +#define SDL_JoystickSetPlayerIndex SDL_SetJoystickPlayerIndex +#define SDL_JoystickSetVirtualAxis SDL_SetJoystickVirtualAxis +#define SDL_JoystickSetVirtualButton SDL_SetJoystickVirtualButton +#define SDL_JoystickSetVirtualHat SDL_SetJoystickVirtualHat +#define SDL_JoystickUpdate SDL_UpdateJoysticks + +/* ##SDL_keyboard.h */ +#define SDL_IsScreenKeyboardShown SDL_ScreenKeyboardShown +#define SDL_IsTextInputActive SDL_TextInputActive + +/* ##SDL_keycode.h */ +#define KMOD_ALT SDL_KMOD_ALT +#define KMOD_CAPS SDL_KMOD_CAPS +#define KMOD_CTRL SDL_KMOD_CTRL +#define KMOD_GUI SDL_KMOD_GUI +#define KMOD_LALT SDL_KMOD_LALT +#define KMOD_LCTRL SDL_KMOD_LCTRL +#define KMOD_LGUI SDL_KMOD_LGUI +#define KMOD_LSHIFT SDL_KMOD_LSHIFT +#define KMOD_MODE SDL_KMOD_MODE +#define KMOD_NONE SDL_KMOD_NONE +#define KMOD_NUM SDL_KMOD_NUM +#define KMOD_RALT SDL_KMOD_RALT +#define KMOD_RCTRL SDL_KMOD_RCTRL +#define KMOD_RGUI SDL_KMOD_RGUI +#define KMOD_RSHIFT SDL_KMOD_RSHIFT +#define KMOD_SCROLL SDL_KMOD_SCROLL +#define KMOD_SHIFT SDL_KMOD_SHIFT +#define SDLK_AUDIOFASTFORWARD SDLK_MEDIA_FAST_FORWARD +#define SDLK_AUDIOMUTE SDLK_MUTE +#define SDLK_AUDIONEXT SDLK_MEDIA_NEXT_TRACK +#define SDLK_AUDIOPLAY SDLK_MEDIA_PLAY +#define SDLK_AUDIOPREV SDLK_MEDIA_PREVIOUS_TRACK +#define SDLK_AUDIOREWIND SDLK_MEDIA_REWIND +#define SDLK_AUDIOSTOP SDLK_MEDIA_STOP +#define SDLK_BACKQUOTE SDLK_GRAVE +#define SDLK_EJECT SDLK_MEDIA_EJECT +#define SDLK_MEDIASELECT SDLK_MEDIA_SELECT +#define SDLK_QUOTE SDLK_APOSTROPHE +#define SDLK_QUOTEDBL SDLK_DBLAPOSTROPHE +#define SDLK_a SDLK_A +#define SDLK_b SDLK_B +#define SDLK_c SDLK_C +#define SDLK_d SDLK_D +#define SDLK_e SDLK_E +#define SDLK_f SDLK_F +#define SDLK_g SDLK_G +#define SDLK_h SDLK_H +#define SDLK_i SDLK_I +#define SDLK_j SDLK_J +#define SDLK_k SDLK_K +#define SDLK_l SDLK_L +#define SDLK_m SDLK_M +#define SDLK_n SDLK_N +#define SDLK_o SDLK_O +#define SDLK_p SDLK_P +#define SDLK_q SDLK_Q +#define SDLK_r SDLK_R +#define SDLK_s SDLK_S +#define SDLK_t SDLK_T +#define SDLK_u SDLK_U +#define SDLK_v SDLK_V +#define SDLK_w SDLK_W +#define SDLK_x SDLK_X +#define SDLK_y SDLK_Y +#define SDLK_z SDLK_Z + +/* ##SDL_log.h */ +#define SDL_LogGetOutputFunction SDL_GetLogOutputFunction +#define SDL_LogGetPriority SDL_GetLogPriority +#define SDL_LogResetPriorities SDL_ResetLogPriorities +#define SDL_LogSetAllPriority SDL_SetLogPriorities +#define SDL_LogSetOutputFunction SDL_SetLogOutputFunction +#define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT + +/* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK +#define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT +#define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT +#define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER +#define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT +#define SDL_SYSTEM_CURSOR_NO SDL_SYSTEM_CURSOR_NOT_ALLOWED +#define SDL_SYSTEM_CURSOR_SIZEALL SDL_SYSTEM_CURSOR_MOVE +#define SDL_SYSTEM_CURSOR_SIZENESW SDL_SYSTEM_CURSOR_NESW_RESIZE +#define SDL_SYSTEM_CURSOR_SIZENS SDL_SYSTEM_CURSOR_NS_RESIZE +#define SDL_SYSTEM_CURSOR_SIZENWSE SDL_SYSTEM_CURSOR_NWSE_RESIZE +#define SDL_SYSTEM_CURSOR_SIZEWE SDL_SYSTEM_CURSOR_EW_RESIZE +#define SDL_SYSTEM_CURSOR_WAITARROW SDL_SYSTEM_CURSOR_PROGRESS +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOM SDL_SYSTEM_CURSOR_S_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOMLEFT SDL_SYSTEM_CURSOR_SW_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOMRIGHT SDL_SYSTEM_CURSOR_SE_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_LEFT SDL_SYSTEM_CURSOR_W_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_RIGHT SDL_SYSTEM_CURSOR_E_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOP SDL_SYSTEM_CURSOR_N_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOPLEFT SDL_SYSTEM_CURSOR_NW_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOPRIGHT SDL_SYSTEM_CURSOR_NE_RESIZE + +/* ##SDL_mutex.h */ +#define SDL_CondBroadcast SDL_BroadcastCondition +#define SDL_CondSignal SDL_SignalCondition +#define SDL_CondWait SDL_WaitCondition +#define SDL_CondWaitTimeout SDL_WaitConditionTimeout +#define SDL_CreateCond SDL_CreateCondition +#define SDL_DestroyCond SDL_DestroyCondition +#define SDL_SemPost SDL_SignalSemaphore +#define SDL_SemTryWait SDL_TryWaitSemaphore +#define SDL_SemValue SDL_GetSemaphoreValue +#define SDL_SemWait SDL_WaitSemaphore +#define SDL_SemWaitTimeout SDL_WaitSemaphoreTimeout + +/* ##SDL_mutex.h */ +#define SDL_cond SDL_Condition +#define SDL_mutex SDL_Mutex +#define SDL_sem SDL_Semaphore + +/* ##SDL_pixels.h */ +#define SDL_AllocFormat SDL_GetPixelFormatDetails +#define SDL_AllocPalette SDL_CreatePalette +#define SDL_Colour SDL_Color +#define SDL_FreePalette SDL_DestroyPalette +#define SDL_MasksToPixelFormatEnum SDL_GetPixelFormatForMasks +#define SDL_PIXELFORMAT_BGR444 SDL_PIXELFORMAT_XBGR4444 +#define SDL_PIXELFORMAT_BGR555 SDL_PIXELFORMAT_XBGR1555 +#define SDL_PIXELFORMAT_BGR888 SDL_PIXELFORMAT_XBGR8888 +#define SDL_PIXELFORMAT_RGB444 SDL_PIXELFORMAT_XRGB4444 +#define SDL_PIXELFORMAT_RGB555 SDL_PIXELFORMAT_XRGB1555 +#define SDL_PIXELFORMAT_RGB888 SDL_PIXELFORMAT_XRGB8888 +#define SDL_PixelFormatEnumToMasks SDL_GetMasksForPixelFormat + +/* ##SDL_rect.h */ +#define SDL_EncloseFPoints SDL_GetRectEnclosingPointsFloat +#define SDL_EnclosePoints SDL_GetRectEnclosingPoints +#define SDL_FRectEmpty SDL_RectEmptyFloat +#define SDL_FRectEquals SDL_RectsEqualFloat +#define SDL_FRectEqualsEpsilon SDL_RectsEqualEpsilon +#define SDL_HasIntersection SDL_HasRectIntersection +#define SDL_HasIntersectionF SDL_HasRectIntersectionFloat +#define SDL_IntersectFRect SDL_GetRectIntersectionFloat +#define SDL_IntersectFRectAndLine SDL_GetRectAndLineIntersectionFloat +#define SDL_IntersectRect SDL_GetRectIntersection +#define SDL_IntersectRectAndLine SDL_GetRectAndLineIntersection +#define SDL_PointInFRect SDL_PointInRectFloat +#define SDL_RectEquals SDL_RectsEqual +#define SDL_UnionFRect SDL_GetRectUnionFloat +#define SDL_UnionRect SDL_GetRectUnion + +/* ##SDL_render.h */ +#define SDL_GetRendererOutputSize SDL_GetCurrentRenderOutputSize +#define SDL_RenderCopy SDL_RenderTexture +#define SDL_RenderCopyEx SDL_RenderTextureRotated +#define SDL_RenderCopyExF SDL_RenderTextureRotated +#define SDL_RenderCopyF SDL_RenderTexture +#define SDL_RenderDrawLine SDL_RenderLine +#define SDL_RenderDrawLineF SDL_RenderLine +#define SDL_RenderDrawLines SDL_RenderLines +#define SDL_RenderDrawLinesF SDL_RenderLines +#define SDL_RenderDrawPoint SDL_RenderPoint +#define SDL_RenderDrawPointF SDL_RenderPoint +#define SDL_RenderDrawPoints SDL_RenderPoints +#define SDL_RenderDrawPointsF SDL_RenderPoints +#define SDL_RenderDrawRect SDL_RenderRect +#define SDL_RenderDrawRectF SDL_RenderRect +#define SDL_RenderDrawRects SDL_RenderRects +#define SDL_RenderDrawRectsF SDL_RenderRects +#define SDL_RenderFillRectF SDL_RenderFillRect +#define SDL_RenderFillRectsF SDL_RenderFillRects +#define SDL_RendererFlip SDL_FlipMode +#define SDL_RenderFlush SDL_FlushRenderer +#define SDL_RenderGetClipRect SDL_GetRenderClipRect +#define SDL_RenderGetLogicalSize SDL_GetRenderLogicalPresentation +#define SDL_RenderGetMetalCommandEncoder SDL_GetRenderMetalCommandEncoder +#define SDL_RenderGetMetalLayer SDL_GetRenderMetalLayer +#define SDL_RenderGetScale SDL_GetRenderScale +#define SDL_RenderGetViewport SDL_GetRenderViewport +#define SDL_RenderGetWindow SDL_GetRenderWindow +#define SDL_RenderIsClipEnabled SDL_RenderClipEnabled +#define SDL_RenderLogicalToWindow SDL_RenderCoordinatesToWindow +#define SDL_RenderSetClipRect SDL_SetRenderClipRect +#define SDL_RenderSetLogicalSize SDL_SetRenderLogicalPresentation +#define SDL_RenderSetScale SDL_SetRenderScale +#define SDL_RenderSetVSync SDL_SetRenderVSync +#define SDL_RenderSetViewport SDL_SetRenderViewport +#define SDL_RenderWindowToLogical SDL_RenderCoordinatesFromWindow +#define SDL_ScaleModeLinear SDL_SCALEMODE_LINEAR +#define SDL_ScaleModeNearest SDL_SCALEMODE_NEAREST + +/* ##SDL_rwops.h */ +#define RW_SEEK_CUR SDL_IO_SEEK_CUR +#define RW_SEEK_END SDL_IO_SEEK_END +#define RW_SEEK_SET SDL_IO_SEEK_SET +#define SDL_RWFromConstMem SDL_IOFromConstMem +#define SDL_RWFromFile SDL_IOFromFile +#define SDL_RWFromMem SDL_IOFromMem +#define SDL_RWclose SDL_CloseIO +#define SDL_RWops SDL_IOStream +#define SDL_RWread SDL_ReadIO +#define SDL_RWseek SDL_SeekIO +#define SDL_RWsize SDL_GetIOSize +#define SDL_RWtell SDL_TellIO +#define SDL_RWwrite SDL_WriteIO +#define SDL_ReadBE16 SDL_ReadU16BE +#define SDL_ReadBE32 SDL_ReadU32BE +#define SDL_ReadBE64 SDL_ReadU64BE +#define SDL_ReadLE16 SDL_ReadU16LE +#define SDL_ReadLE32 SDL_ReadU32LE +#define SDL_ReadLE64 SDL_ReadU64LE +#define SDL_WriteBE16 SDL_WriteU16BE +#define SDL_WriteBE32 SDL_WriteU32BE +#define SDL_WriteBE64 SDL_WriteU64BE +#define SDL_WriteLE16 SDL_WriteU16LE +#define SDL_WriteLE32 SDL_WriteU32LE +#define SDL_WriteLE64 SDL_WriteU64LE + +/* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT +#define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD +#define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE +#define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK +#define SDL_SCANCODE_AUDIOPLAY SDL_SCANCODE_MEDIA_PLAY +#define SDL_SCANCODE_AUDIOPREV SDL_SCANCODE_MEDIA_PREVIOUS_TRACK +#define SDL_SCANCODE_AUDIOREWIND SDL_SCANCODE_MEDIA_REWIND +#define SDL_SCANCODE_AUDIOSTOP SDL_SCANCODE_MEDIA_STOP +#define SDL_SCANCODE_EJECT SDL_SCANCODE_MEDIA_EJECT +#define SDL_SCANCODE_MEDIASELECT SDL_SCANCODE_MEDIA_SELECT + +/* ##SDL_sensor.h */ +#define SDL_SensorClose SDL_CloseSensor +#define SDL_SensorFromInstanceID SDL_GetSensorFromID +#define SDL_SensorGetData SDL_GetSensorData +#define SDL_SensorGetInstanceID SDL_GetSensorID +#define SDL_SensorGetName SDL_GetSensorName +#define SDL_SensorGetNonPortableType SDL_GetSensorNonPortableType +#define SDL_SensorGetType SDL_GetSensorType +#define SDL_SensorOpen SDL_OpenSensor +#define SDL_SensorUpdate SDL_UpdateSensors + +/* ##SDL_stdinc.h */ +#define SDL_FALSE false +#define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow +#define SDL_strtokr SDL_strtok_r + +/* ##SDL_surface.h */ +#define SDL_BlitScaled SDL_BlitSurfaceScaled +#define SDL_ConvertSurfaceFormat SDL_ConvertSurface +#define SDL_FillRect SDL_FillSurfaceRect +#define SDL_FillRects SDL_FillSurfaceRects +#define SDL_FreeSurface SDL_DestroySurface +#define SDL_GetClipRect SDL_GetSurfaceClipRect +#define SDL_GetColorKey SDL_GetSurfaceColorKey +#define SDL_HasColorKey SDL_SurfaceHasColorKey +#define SDL_HasSurfaceRLE SDL_SurfaceHasRLE +#define SDL_LoadBMP_RW SDL_LoadBMP_IO +#define SDL_LowerBlit SDL_BlitSurfaceUnchecked +#define SDL_LowerBlitScaled SDL_BlitSurfaceUncheckedScaled +#define SDL_PREALLOC SDL_SURFACE_PREALLOCATED +#define SDL_SIMD_ALIGNED SDL_SURFACE_SIMD_ALIGNED +#define SDL_SaveBMP_RW SDL_SaveBMP_IO +#define SDL_SetClipRect SDL_SetSurfaceClipRect +#define SDL_SetColorKey SDL_SetSurfaceColorKey +#define SDL_UpperBlit SDL_BlitSurface +#define SDL_UpperBlitScaled SDL_BlitSurfaceScaled + +/* ##SDL_system.h */ +#define SDL_AndroidBackButton SDL_SendAndroidBackButton +#define SDL_AndroidGetActivity SDL_GetAndroidActivity +#define SDL_AndroidGetExternalStoragePath SDL_GetAndroidExternalStoragePath +#define SDL_AndroidGetExternalStorageState SDL_GetAndroidExternalStorageState +#define SDL_AndroidGetInternalStoragePath SDL_GetAndroidInternalStoragePath +#define SDL_AndroidGetJNIEnv SDL_GetAndroidJNIEnv +#define SDL_AndroidRequestPermission SDL_RequestAndroidPermission +#define SDL_AndroidRequestPermissionCallback SDL_RequestAndroidPermissionCallback +#define SDL_AndroidSendMessage SDL_SendAndroidMessage +#define SDL_AndroidShowToast SDL_ShowAndroidToast +#define SDL_DXGIGetOutputInfo SDL_GetDXGIOutputInfo +#define SDL_Direct3D9GetAdapterIndex SDL_GetDirect3D9AdapterIndex +#define SDL_GDKGetDefaultUser SDL_GetGDKDefaultUser +#define SDL_GDKGetTaskQueue SDL_GetGDKTaskQueue +#define SDL_LinuxSetThreadPriority SDL_SetLinuxThreadPriority +#define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy +#define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground +#define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground +#define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback +#define SDL_iOSSetEventPump SDL_SetiOSEventPump +#define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback +#define SDL_iPhoneSetEventPump SDL_SetiOSEventPump + +/* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority +#define SDL_TLSCleanup SDL_CleanupTLS +#define SDL_TLSGet SDL_GetTLS +#define SDL_TLSSet SDL_SetTLS +#define SDL_threadID SDL_ThreadID + +/* ##SDL_timer.h */ +#define SDL_GetTicks64 SDL_GetTicks + +/* ##SDL_version.h */ +#define SDL_COMPILEDVERSION SDL_VERSION +#define SDL_PATCHLEVEL SDL_MICRO_VERSION + +/* ##SDL_video.h */ +#define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile +#define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode +#define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation +#define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint +#define SDL_GetRectDisplayIndex SDL_GetDisplayForRect +#define SDL_GetWindowDisplayIndex SDL_GetDisplayForWindow +#define SDL_GetWindowDisplayMode SDL_GetWindowFullscreenMode +#define SDL_HasWindowSurface SDL_WindowHasSurface +#define SDL_IsScreenSaverEnabled SDL_ScreenSaverEnabled +#define SDL_SetWindowDisplayMode SDL_SetWindowFullscreenMode +#define SDL_WINDOW_ALLOW_HIGHDPI SDL_WINDOW_HIGH_PIXEL_DENSITY +#define SDL_WINDOW_INPUT_GRABBED SDL_WINDOW_MOUSE_GRABBED +#define SDL_WINDOW_SKIP_TASKBAR SDL_WINDOW_UTILITY + +#elif !defined(SDL_DISABLE_OLD_NAMES) + +/* ##SDL_atomic.h */ +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer +#define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer +#define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock +#define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock +#define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt + +/* ##SDL_audio.h */ +#define AUDIO_F32 AUDIO_F32_renamed_SDL_AUDIO_F32LE +#define AUDIO_F32LSB AUDIO_F32LSB_renamed_SDL_AUDIO_F32LE +#define AUDIO_F32MSB AUDIO_F32MSB_renamed_SDL_AUDIO_F32BE +#define AUDIO_F32SYS AUDIO_F32SYS_renamed_SDL_AUDIO_F32 +#define AUDIO_S16 AUDIO_S16_renamed_SDL_AUDIO_S16LE +#define AUDIO_S16LSB AUDIO_S16LSB_renamed_SDL_AUDIO_S16LE +#define AUDIO_S16MSB AUDIO_S16MSB_renamed_SDL_AUDIO_S16BE +#define AUDIO_S16SYS AUDIO_S16SYS_renamed_SDL_AUDIO_S16 +#define AUDIO_S32 AUDIO_S32_renamed_SDL_AUDIO_S32LE +#define AUDIO_S32LSB AUDIO_S32LSB_renamed_SDL_AUDIO_S32LE +#define AUDIO_S32MSB AUDIO_S32MSB_renamed_SDL_AUDIO_S32BE +#define AUDIO_S32SYS AUDIO_S32SYS_renamed_SDL_AUDIO_S32 +#define AUDIO_S8 AUDIO_S8_renamed_SDL_AUDIO_S8 +#define AUDIO_U8 AUDIO_U8_renamed_SDL_AUDIO_U8 +#define SDL_AudioStreamAvailable SDL_AudioStreamAvailable_renamed_SDL_GetAudioStreamAvailable +#define SDL_AudioStreamClear SDL_AudioStreamClear_renamed_SDL_ClearAudioStream +#define SDL_AudioStreamFlush SDL_AudioStreamFlush_renamed_SDL_FlushAudioStream +#define SDL_AudioStreamGet SDL_AudioStreamGet_renamed_SDL_GetAudioStreamData +#define SDL_AudioStreamPut SDL_AudioStreamPut_renamed_SDL_PutAudioStreamData +#define SDL_FreeAudioStream SDL_FreeAudioStream_renamed_SDL_DestroyAudioStream +#define SDL_FreeWAV SDL_FreeWAV_renamed_SDL_free +#define SDL_LoadWAV_RW SDL_LoadWAV_RW_renamed_SDL_LoadWAV_IO +#define SDL_MixAudioFormat SDL_MixAudioFormat_renamed_SDL_MixAudio +#define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream + +/* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores +#define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment + +/* ##SDL_endian.h */ +#define SDL_SwapBE16 SDL_SwapBE16_renamed_SDL_Swap16BE +#define SDL_SwapBE32 SDL_SwapBE32_renamed_SDL_Swap32BE +#define SDL_SwapBE64 SDL_SwapBE64_renamed_SDL_Swap64BE +#define SDL_SwapLE16 SDL_SwapLE16_renamed_SDL_Swap16LE +#define SDL_SwapLE32 SDL_SwapLE32_renamed_SDL_Swap32LE +#define SDL_SwapLE64 SDL_SwapLE64_renamed_SDL_Swap64LE + +/* ##SDL_events.h */ +#define SDL_APP_DIDENTERBACKGROUND SDL_APP_DIDENTERBACKGROUND_renamed_SDL_EVENT_DID_ENTER_BACKGROUND +#define SDL_APP_DIDENTERFOREGROUND SDL_APP_DIDENTERFOREGROUND_renamed_SDL_EVENT_DID_ENTER_FOREGROUND +#define SDL_APP_LOWMEMORY SDL_APP_LOWMEMORY_renamed_SDL_EVENT_LOW_MEMORY +#define SDL_APP_TERMINATING SDL_APP_TERMINATING_renamed_SDL_EVENT_TERMINATING +#define SDL_APP_WILLENTERBACKGROUND SDL_APP_WILLENTERBACKGROUND_renamed_SDL_EVENT_WILL_ENTER_BACKGROUND +#define SDL_APP_WILLENTERFOREGROUND SDL_APP_WILLENTERFOREGROUND_renamed_SDL_EVENT_WILL_ENTER_FOREGROUND +#define SDL_AUDIODEVICEADDED SDL_AUDIODEVICEADDED_renamed_SDL_EVENT_AUDIO_DEVICE_ADDED +#define SDL_AUDIODEVICEREMOVED SDL_AUDIODEVICEREMOVED_renamed_SDL_EVENT_AUDIO_DEVICE_REMOVED +#define SDL_CLIPBOARDUPDATE SDL_CLIPBOARDUPDATE_renamed_SDL_EVENT_CLIPBOARD_UPDATE +#define SDL_CONTROLLERAXISMOTION SDL_CONTROLLERAXISMOTION_renamed_SDL_EVENT_GAMEPAD_AXIS_MOTION +#define SDL_CONTROLLERBUTTONDOWN SDL_CONTROLLERBUTTONDOWN_renamed_SDL_EVENT_GAMEPAD_BUTTON_DOWN +#define SDL_CONTROLLERBUTTONUP SDL_CONTROLLERBUTTONUP_renamed_SDL_EVENT_GAMEPAD_BUTTON_UP +#define SDL_CONTROLLERDEVICEADDED SDL_CONTROLLERDEVICEADDED_renamed_SDL_EVENT_GAMEPAD_ADDED +#define SDL_CONTROLLERDEVICEREMAPPED SDL_CONTROLLERDEVICEREMAPPED_renamed_SDL_EVENT_GAMEPAD_REMAPPED +#define SDL_CONTROLLERDEVICEREMOVED SDL_CONTROLLERDEVICEREMOVED_renamed_SDL_EVENT_GAMEPAD_REMOVED +#define SDL_CONTROLLERSENSORUPDATE SDL_CONTROLLERSENSORUPDATE_renamed_SDL_EVENT_GAMEPAD_SENSOR_UPDATE +#define SDL_CONTROLLERSTEAMHANDLEUPDATED SDL_CONTROLLERSTEAMHANDLEUPDATED_renamed_SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED +#define SDL_CONTROLLERTOUCHPADDOWN SDL_CONTROLLERTOUCHPADDOWN_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN +#define SDL_CONTROLLERTOUCHPADMOTION SDL_CONTROLLERTOUCHPADMOTION_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION +#define SDL_CONTROLLERTOUCHPADUP SDL_CONTROLLERTOUCHPADUP_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_UP +#define SDL_ControllerAxisEvent SDL_ControllerAxisEvent_renamed_SDL_GamepadAxisEvent +#define SDL_ControllerButtonEvent SDL_ControllerButtonEvent_renamed_SDL_GamepadButtonEvent +#define SDL_ControllerDeviceEvent SDL_ControllerDeviceEvent_renamed_SDL_GamepadDeviceEvent +#define SDL_ControllerSensorEvent SDL_ControllerSensorEvent_renamed_SDL_GamepadSensorEvent +#define SDL_ControllerTouchpadEvent SDL_ControllerTouchpadEvent_renamed_SDL_GamepadTouchpadEvent +#define SDL_DISPLAYEVENT_CONNECTED SDL_DISPLAYEVENT_CONNECTED_renamed_SDL_EVENT_DISPLAY_ADDED +#define SDL_DISPLAYEVENT_DISCONNECTED SDL_DISPLAYEVENT_DISCONNECTED_renamed_SDL_EVENT_DISPLAY_REMOVED +#define SDL_DISPLAYEVENT_MOVED SDL_DISPLAYEVENT_MOVED_renamed_SDL_EVENT_DISPLAY_MOVED +#define SDL_DISPLAYEVENT_ORIENTATION SDL_DISPLAYEVENT_ORIENTATION_renamed_SDL_EVENT_DISPLAY_ORIENTATION +#define SDL_DROPBEGIN SDL_DROPBEGIN_renamed_SDL_EVENT_DROP_BEGIN +#define SDL_DROPCOMPLETE SDL_DROPCOMPLETE_renamed_SDL_EVENT_DROP_COMPLETE +#define SDL_DROPFILE SDL_DROPFILE_renamed_SDL_EVENT_DROP_FILE +#define SDL_DROPTEXT SDL_DROPTEXT_renamed_SDL_EVENT_DROP_TEXT +#define SDL_DelEventWatch SDL_DelEventWatch_renamed_SDL_RemoveEventWatch +#define SDL_FINGERDOWN SDL_FINGERDOWN_renamed_SDL_EVENT_FINGER_DOWN +#define SDL_FINGERMOTION SDL_FINGERMOTION_renamed_SDL_EVENT_FINGER_MOTION +#define SDL_FINGERUP SDL_FINGERUP_renamed_SDL_EVENT_FINGER_UP +#define SDL_FIRSTEVENT SDL_FIRSTEVENT_renamed_SDL_EVENT_FIRST +#define SDL_JOYAXISMOTION SDL_JOYAXISMOTION_renamed_SDL_EVENT_JOYSTICK_AXIS_MOTION +#define SDL_JOYBATTERYUPDATED SDL_JOYBATTERYUPDATED_renamed_SDL_EVENT_JOYSTICK_BATTERY_UPDATED +#define SDL_JOYBUTTONDOWN SDL_JOYBUTTONDOWN_renamed_SDL_EVENT_JOYSTICK_BUTTON_DOWN +#define SDL_JOYBUTTONUP SDL_JOYBUTTONUP_renamed_SDL_EVENT_JOYSTICK_BUTTON_UP +#define SDL_JOYDEVICEADDED SDL_JOYDEVICEADDED_renamed_SDL_EVENT_JOYSTICK_ADDED +#define SDL_JOYDEVICEREMOVED SDL_JOYDEVICEREMOVED_renamed_SDL_EVENT_JOYSTICK_REMOVED +#define SDL_JOYBALLMOTION SDL_JOYBALLMOTION_renamed_SDL_EVENT_JOYSTICK_BALL_MOTION +#define SDL_JOYHATMOTION SDL_JOYHATMOTION_renamed_SDL_EVENT_JOYSTICK_HAT_MOTION +#define SDL_KEYDOWN SDL_KEYDOWN_renamed_SDL_EVENT_KEY_DOWN +#define SDL_KEYMAPCHANGED SDL_KEYMAPCHANGED_renamed_SDL_EVENT_KEYMAP_CHANGED +#define SDL_KEYUP SDL_KEYUP_renamed_SDL_EVENT_KEY_UP +#define SDL_LASTEVENT SDL_LASTEVENT_renamed_SDL_EVENT_LAST +#define SDL_LOCALECHANGED SDL_LOCALECHANGED_renamed_SDL_EVENT_LOCALE_CHANGED +#define SDL_MOUSEBUTTONDOWN SDL_MOUSEBUTTONDOWN_renamed_SDL_EVENT_MOUSE_BUTTON_DOWN +#define SDL_MOUSEBUTTONUP SDL_MOUSEBUTTONUP_renamed_SDL_EVENT_MOUSE_BUTTON_UP +#define SDL_MOUSEMOTION SDL_MOUSEMOTION_renamed_SDL_EVENT_MOUSE_MOTION +#define SDL_MOUSEWHEEL SDL_MOUSEWHEEL_renamed_SDL_EVENT_MOUSE_WHEEL +#define SDL_POLLSENTINEL SDL_POLLSENTINEL_renamed_SDL_EVENT_POLL_SENTINEL +#define SDL_QUIT SDL_QUIT_renamed_SDL_EVENT_QUIT +#define SDL_RENDER_DEVICE_RESET SDL_RENDER_DEVICE_RESET_renamed_SDL_EVENT_RENDER_DEVICE_RESET +#define SDL_RENDER_TARGETS_RESET SDL_RENDER_TARGETS_RESET_renamed_SDL_EVENT_RENDER_TARGETS_RESET +#define SDL_SENSORUPDATE SDL_SENSORUPDATE_renamed_SDL_EVENT_SENSOR_UPDATE +#define SDL_TEXTEDITING SDL_TEXTEDITING_renamed_SDL_EVENT_TEXT_EDITING +#define SDL_TEXTEDITING_EXT SDL_TEXTEDITING_EXT_renamed_SDL_EVENT_TEXT_EDITING_EXT +#define SDL_TEXTINPUT SDL_TEXTINPUT_renamed_SDL_EVENT_TEXT_INPUT +#define SDL_USEREVENT SDL_USEREVENT_renamed_SDL_EVENT_USER +#define SDL_WINDOWEVENT_CLOSE SDL_WINDOWEVENT_CLOSE_renamed_SDL_EVENT_WINDOW_CLOSE_REQUESTED +#define SDL_WINDOWEVENT_DISPLAY_CHANGED SDL_WINDOWEVENT_DISPLAY_CHANGED_renamed_SDL_EVENT_WINDOW_DISPLAY_CHANGED +#define SDL_WINDOWEVENT_ENTER SDL_WINDOWEVENT_ENTER_renamed_SDL_EVENT_WINDOW_MOUSE_ENTER +#define SDL_WINDOWEVENT_EXPOSED SDL_WINDOWEVENT_EXPOSED_renamed_SDL_EVENT_WINDOW_EXPOSED +#define SDL_WINDOWEVENT_FOCUS_GAINED SDL_WINDOWEVENT_FOCUS_GAINED_renamed_SDL_EVENT_WINDOW_FOCUS_GAINED +#define SDL_WINDOWEVENT_FOCUS_LOST SDL_WINDOWEVENT_FOCUS_LOST_renamed_SDL_EVENT_WINDOW_FOCUS_LOST +#define SDL_WINDOWEVENT_HIDDEN SDL_WINDOWEVENT_HIDDEN_renamed_SDL_EVENT_WINDOW_HIDDEN +#define SDL_WINDOWEVENT_HIT_TEST SDL_WINDOWEVENT_HIT_TEST_renamed_SDL_EVENT_WINDOW_HIT_TEST +#define SDL_WINDOWEVENT_ICCPROF_CHANGED SDL_WINDOWEVENT_ICCPROF_CHANGED_renamed_SDL_EVENT_WINDOW_ICCPROF_CHANGED +#define SDL_WINDOWEVENT_LEAVE SDL_WINDOWEVENT_LEAVE_renamed_SDL_EVENT_WINDOW_MOUSE_LEAVE +#define SDL_WINDOWEVENT_MAXIMIZED SDL_WINDOWEVENT_MAXIMIZED_renamed_SDL_EVENT_WINDOW_MAXIMIZED +#define SDL_WINDOWEVENT_MINIMIZED SDL_WINDOWEVENT_MINIMIZED_renamed_SDL_EVENT_WINDOW_MINIMIZED +#define SDL_WINDOWEVENT_MOVED SDL_WINDOWEVENT_MOVED_renamed_SDL_EVENT_WINDOW_MOVED +#define SDL_WINDOWEVENT_RESIZED SDL_WINDOWEVENT_RESIZED_renamed_SDL_EVENT_WINDOW_RESIZED +#define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED +#define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN +#define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED +#define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction + +/* ##SDL_gamecontroller.h */ +#define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID +#define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX +#define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT +#define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX +#define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY +#define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER +#define SDL_CONTROLLER_AXIS_TRIGGERRIGHT SDL_CONTROLLER_AXIS_TRIGGERRIGHT_renamed_SDL_GAMEPAD_AXIS_RIGHT_TRIGGER +#define SDL_CONTROLLER_BINDTYPE_AXIS SDL_CONTROLLER_BINDTYPE_AXIS_renamed_SDL_GAMEPAD_BINDTYPE_AXIS +#define SDL_CONTROLLER_BINDTYPE_BUTTON SDL_CONTROLLER_BINDTYPE_BUTTON_renamed_SDL_GAMEPAD_BINDTYPE_BUTTON +#define SDL_CONTROLLER_BINDTYPE_HAT SDL_CONTROLLER_BINDTYPE_HAT_renamed_SDL_GAMEPAD_BINDTYPE_HAT +#define SDL_CONTROLLER_BINDTYPE_NONE SDL_CONTROLLER_BINDTYPE_NONE_renamed_SDL_GAMEPAD_BINDTYPE_NONE +#define SDL_CONTROLLER_BUTTON_A SDL_CONTROLLER_BUTTON_A_renamed_SDL_GAMEPAD_BUTTON_SOUTH +#define SDL_CONTROLLER_BUTTON_B SDL_CONTROLLER_BUTTON_B_renamed_SDL_GAMEPAD_BUTTON_EAST +#define SDL_CONTROLLER_BUTTON_BACK SDL_CONTROLLER_BUTTON_BACK_renamed_SDL_GAMEPAD_BUTTON_BACK +#define SDL_CONTROLLER_BUTTON_DPAD_DOWN SDL_CONTROLLER_BUTTON_DPAD_DOWN_renamed_SDL_GAMEPAD_BUTTON_DPAD_DOWN +#define SDL_CONTROLLER_BUTTON_DPAD_LEFT SDL_CONTROLLER_BUTTON_DPAD_LEFT_renamed_SDL_GAMEPAD_BUTTON_DPAD_LEFT +#define SDL_CONTROLLER_BUTTON_DPAD_RIGHT SDL_CONTROLLER_BUTTON_DPAD_RIGHT_renamed_SDL_GAMEPAD_BUTTON_DPAD_RIGHT +#define SDL_CONTROLLER_BUTTON_DPAD_UP SDL_CONTROLLER_BUTTON_DPAD_UP_renamed_SDL_GAMEPAD_BUTTON_DPAD_UP +#define SDL_CONTROLLER_BUTTON_GUIDE SDL_CONTROLLER_BUTTON_GUIDE_renamed_SDL_GAMEPAD_BUTTON_GUIDE +#define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID +#define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER +#define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT +#define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 +#define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 +#define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 +#define SDL_CONTROLLER_BUTTON_PADDLE3 SDL_CONTROLLER_BUTTON_PADDLE3_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2 +#define SDL_CONTROLLER_BUTTON_PADDLE4 SDL_CONTROLLER_BUTTON_PADDLE4_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE2 +#define SDL_CONTROLLER_BUTTON_RIGHTSHOULDER SDL_CONTROLLER_BUTTON_RIGHTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER +#define SDL_CONTROLLER_BUTTON_RIGHTSTICK SDL_CONTROLLER_BUTTON_RIGHTSTICK_renamed_SDL_GAMEPAD_BUTTON_RIGHT_STICK +#define SDL_CONTROLLER_BUTTON_START SDL_CONTROLLER_BUTTON_START_renamed_SDL_GAMEPAD_BUTTON_START +#define SDL_CONTROLLER_BUTTON_TOUCHPAD SDL_CONTROLLER_BUTTON_TOUCHPAD_renamed_SDL_GAMEPAD_BUTTON_TOUCHPAD +#define SDL_CONTROLLER_BUTTON_X SDL_CONTROLLER_BUTTON_X_renamed_SDL_GAMEPAD_BUTTON_WEST +#define SDL_CONTROLLER_BUTTON_Y SDL_CONTROLLER_BUTTON_Y_renamed_SDL_GAMEPAD_BUTTON_NORTH +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT +#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO +#define SDL_CONTROLLER_TYPE_PS3 SDL_CONTROLLER_TYPE_PS3_renamed_SDL_GAMEPAD_TYPE_PS3 +#define SDL_CONTROLLER_TYPE_PS4 SDL_CONTROLLER_TYPE_PS4_renamed_SDL_GAMEPAD_TYPE_PS4 +#define SDL_CONTROLLER_TYPE_PS5 SDL_CONTROLLER_TYPE_PS5_renamed_SDL_GAMEPAD_TYPE_PS5 +#define SDL_CONTROLLER_TYPE_UNKNOWN SDL_CONTROLLER_TYPE_UNKNOWN_renamed_SDL_GAMEPAD_TYPE_STANDARD +#define SDL_CONTROLLER_TYPE_VIRTUAL SDL_CONTROLLER_TYPE_VIRTUAL_renamed_SDL_GAMEPAD_TYPE_VIRTUAL +#define SDL_CONTROLLER_TYPE_XBOX360 SDL_CONTROLLER_TYPE_XBOX360_renamed_SDL_GAMEPAD_TYPE_XBOX360 +#define SDL_CONTROLLER_TYPE_XBOXONE SDL_CONTROLLER_TYPE_XBOXONE_renamed_SDL_GAMEPAD_TYPE_XBOXONE +#define SDL_GameController SDL_GameController_renamed_SDL_Gamepad +#define SDL_GameControllerAddMapping SDL_GameControllerAddMapping_renamed_SDL_AddGamepadMapping +#define SDL_GameControllerAddMappingsFromFile SDL_GameControllerAddMappingsFromFile_renamed_SDL_AddGamepadMappingsFromFile +#define SDL_GameControllerAddMappingsFromRW SDL_GameControllerAddMappingsFromRW_renamed_SDL_AddGamepadMappingsFromIO +#define SDL_GameControllerAxis SDL_GameControllerAxis_renamed_SDL_GamepadAxis +#define SDL_GameControllerBindType SDL_GameControllerBindType_renamed_SDL_GamepadBindingType +#define SDL_GameControllerButton SDL_GameControllerButton_renamed_SDL_GamepadButton +#define SDL_GameControllerClose SDL_GameControllerClose_renamed_SDL_CloseGamepad +#define SDL_GameControllerFromInstanceID SDL_GameControllerFromInstanceID_renamed_SDL_GetGamepadFromID +#define SDL_GameControllerFromPlayerIndex SDL_GameControllerFromPlayerIndex_renamed_SDL_GetGamepadFromPlayerIndex +#define SDL_GameControllerGetAppleSFSymbolsNameForAxis SDL_GameControllerGetAppleSFSymbolsNameForAxis_renamed_SDL_GetGamepadAppleSFSymbolsNameForAxis +#define SDL_GameControllerGetAppleSFSymbolsNameForButton SDL_GameControllerGetAppleSFSymbolsNameForButton_renamed_SDL_GetGamepadAppleSFSymbolsNameForButton +#define SDL_GameControllerGetAttached SDL_GameControllerGetAttached_renamed_SDL_GamepadConnected +#define SDL_GameControllerGetAxis SDL_GameControllerGetAxis_renamed_SDL_GetGamepadAxis +#define SDL_GameControllerGetAxisFromString SDL_GameControllerGetAxisFromString_renamed_SDL_GetGamepadAxisFromString +#define SDL_GameControllerGetButton SDL_GameControllerGetButton_renamed_SDL_GetGamepadButton +#define SDL_GameControllerGetButtonFromString SDL_GameControllerGetButtonFromString_renamed_SDL_GetGamepadButtonFromString +#define SDL_GameControllerGetFirmwareVersion SDL_GameControllerGetFirmwareVersion_renamed_SDL_GetGamepadFirmwareVersion +#define SDL_GameControllerGetJoystick SDL_GameControllerGetJoystick_renamed_SDL_GetGamepadJoystick +#define SDL_GameControllerGetNumTouchpadFingers SDL_GameControllerGetNumTouchpadFingers_renamed_SDL_GetNumGamepadTouchpadFingers +#define SDL_GameControllerGetNumTouchpads SDL_GameControllerGetNumTouchpads_renamed_SDL_GetNumGamepadTouchpads +#define SDL_GameControllerGetPlayerIndex SDL_GameControllerGetPlayerIndex_renamed_SDL_GetGamepadPlayerIndex +#define SDL_GameControllerGetProduct SDL_GameControllerGetProduct_renamed_SDL_GetGamepadProduct +#define SDL_GameControllerGetProductVersion SDL_GameControllerGetProductVersion_renamed_SDL_GetGamepadProductVersion +#define SDL_GameControllerGetSensorData SDL_GameControllerGetSensorData_renamed_SDL_GetGamepadSensorData +#define SDL_GameControllerGetSensorDataRate SDL_GameControllerGetSensorDataRate_renamed_SDL_GetGamepadSensorDataRate +#define SDL_GameControllerGetSerial SDL_GameControllerGetSerial_renamed_SDL_GetGamepadSerial +#define SDL_GameControllerGetSteamHandle SDL_GameControllerGetSteamHandle_renamed_SDL_GetGamepadSteamHandle +#define SDL_GameControllerGetStringForAxis SDL_GameControllerGetStringForAxis_renamed_SDL_GetGamepadStringForAxis +#define SDL_GameControllerGetStringForButton SDL_GameControllerGetStringForButton_renamed_SDL_GetGamepadStringForButton +#define SDL_GameControllerGetTouchpadFinger SDL_GameControllerGetTouchpadFinger_renamed_SDL_GetGamepadTouchpadFinger +#define SDL_GameControllerGetType SDL_GameControllerGetType_renamed_SDL_GetGamepadType +#define SDL_GameControllerGetVendor SDL_GameControllerGetVendor_renamed_SDL_GetGamepadVendor +#define SDL_GameControllerHasAxis SDL_GameControllerHasAxis_renamed_SDL_GamepadHasAxis +#define SDL_GameControllerHasButton SDL_GameControllerHasButton_renamed_SDL_GamepadHasButton +#define SDL_GameControllerHasSensor SDL_GameControllerHasSensor_renamed_SDL_GamepadHasSensor +#define SDL_GameControllerIsSensorEnabled SDL_GameControllerIsSensorEnabled_renamed_SDL_GamepadSensorEnabled +#define SDL_GameControllerMapping SDL_GameControllerMapping_renamed_SDL_GetGamepadMapping +#define SDL_GameControllerMappingForDeviceIndex SDL_GameControllerMappingForDeviceIndex_renamed_SDL_GetGamepadMappingForDeviceIndex +#define SDL_GameControllerMappingForGUID SDL_GameControllerMappingForGUID_renamed_SDL_GetGamepadMappingForGUID +#define SDL_GameControllerName SDL_GameControllerName_renamed_SDL_GetGamepadName +#define SDL_GameControllerOpen SDL_GameControllerOpen_renamed_SDL_OpenGamepad +#define SDL_GameControllerPath SDL_GameControllerPath_renamed_SDL_GetGamepadPath +#define SDL_GameControllerRumble SDL_GameControllerRumble_renamed_SDL_RumbleGamepad +#define SDL_GameControllerRumbleTriggers SDL_GameControllerRumbleTriggers_renamed_SDL_RumbleGamepadTriggers +#define SDL_GameControllerSendEffect SDL_GameControllerSendEffect_renamed_SDL_SendGamepadEffect +#define SDL_GameControllerSetLED SDL_GameControllerSetLED_renamed_SDL_SetGamepadLED +#define SDL_GameControllerSetPlayerIndex SDL_GameControllerSetPlayerIndex_renamed_SDL_SetGamepadPlayerIndex +#define SDL_GameControllerSetSensorEnabled SDL_GameControllerSetSensorEnabled_renamed_SDL_SetGamepadSensorEnabled +#define SDL_GameControllerType SDL_GameControllerType_renamed_SDL_GamepadType +#define SDL_GameControllerUpdate SDL_GameControllerUpdate_renamed_SDL_UpdateGamepads +#define SDL_INIT_GAMECONTROLLER SDL_INIT_GAMECONTROLLER_renamed_SDL_INIT_GAMEPAD +#define SDL_IsGameController SDL_IsGameController_renamed_SDL_IsGamepad + +/* ##SDL_guid.h */ +#define SDL_GUIDFromString SDL_GUIDFromString_renamed_SDL_StringToGUID + +/* ##SDL_haptic.h */ +#define SDL_HapticClose SDL_HapticClose_renamed_SDL_CloseHaptic +#define SDL_HapticDestroyEffect SDL_HapticDestroyEffect_renamed_SDL_DestroyHapticEffect +#define SDL_HapticGetEffectStatus SDL_HapticGetEffectStatus_renamed_SDL_GetHapticEffectStatus +#define SDL_HapticNewEffect SDL_HapticNewEffect_renamed_SDL_CreateHapticEffect +#define SDL_HapticNumAxes SDL_HapticNumAxes_renamed_SDL_GetNumHapticAxes +#define SDL_HapticNumEffects SDL_HapticNumEffects_renamed_SDL_GetMaxHapticEffects +#define SDL_HapticNumEffectsPlaying SDL_HapticNumEffectsPlaying_renamed_SDL_GetMaxHapticEffectsPlaying +#define SDL_HapticOpen SDL_HapticOpen_renamed_SDL_OpenHaptic +#define SDL_HapticOpenFromJoystick SDL_HapticOpenFromJoystick_renamed_SDL_OpenHapticFromJoystick +#define SDL_HapticOpenFromMouse SDL_HapticOpenFromMouse_renamed_SDL_OpenHapticFromMouse +#define SDL_HapticPause SDL_HapticPause_renamed_SDL_PauseHaptic +#define SDL_HapticQuery SDL_HapticQuery_renamed_SDL_GetHapticFeatures +#define SDL_HapticRumbleInit SDL_HapticRumbleInit_renamed_SDL_InitHapticRumble +#define SDL_HapticRumblePlay SDL_HapticRumblePlay_renamed_SDL_PlayHapticRumble +#define SDL_HapticRumbleStop SDL_HapticRumbleStop_renamed_SDL_StopHapticRumble +#define SDL_HapticRunEffect SDL_HapticRunEffect_renamed_SDL_RunHapticEffect +#define SDL_HapticSetAutocenter SDL_HapticSetAutocenter_renamed_SDL_SetHapticAutocenter +#define SDL_HapticSetGain SDL_HapticSetGain_renamed_SDL_SetHapticGain +#define SDL_HapticStopAll SDL_HapticStopAll_renamed_SDL_StopHapticEffects +#define SDL_HapticStopEffect SDL_HapticStopEffect_renamed_SDL_StopHapticEffect +#define SDL_HapticUnpause SDL_HapticUnpause_renamed_SDL_ResumeHaptic +#define SDL_HapticUpdateEffect SDL_HapticUpdateEffect_renamed_SDL_UpdateHapticEffect +#define SDL_JoystickIsHaptic SDL_JoystickIsHaptic_renamed_SDL_IsJoystickHaptic +#define SDL_MouseIsHaptic SDL_MouseIsHaptic_renamed_SDL_IsMouseHaptic + +/* ##SDL_hints.h */ +#define SDL_DelHintCallback SDL_DelHintCallback_renamed_SDL_RemoveHintCallback +#define SDL_HINT_ALLOW_TOPMOST SDL_HINT_ALLOW_TOPMOST_renamed_SDL_HINT_WINDOW_ALLOW_TOPMOST +#define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT +#define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT +#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS +#define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES +#define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC +#define SDL_HINT_LINUX_JOYSTICK_DEADZONES SDL_HINT_LINUX_JOYSTICK_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_DEADZONES + +/* ##SDL_joystick.h */ +#define SDL_JOYSTICK_TYPE_GAMECONTROLLER SDL_JOYSTICK_TYPE_GAMECONTROLLER_renamed_SDL_JOYSTICK_TYPE_GAMEPAD +#define SDL_JoystickAttachVirtualEx SDL_JoystickAttachVirtualEx_renamed_SDL_AttachVirtualJoystick +#define SDL_JoystickClose SDL_JoystickClose_renamed_SDL_CloseJoystick +#define SDL_JoystickDetachVirtual SDL_JoystickDetachVirtual_renamed_SDL_DetachVirtualJoystick +#define SDL_JoystickFromInstanceID SDL_JoystickFromInstanceID_renamed_SDL_GetJoystickFromID +#define SDL_JoystickFromPlayerIndex SDL_JoystickFromPlayerIndex_renamed_SDL_GetJoystickFromPlayerIndex +#define SDL_JoystickGUID SDL_JoystickGUID_renamed_SDL_GUID +#define SDL_JoystickGetAttached SDL_JoystickGetAttached_renamed_SDL_JoystickConnected +#define SDL_JoystickGetAxis SDL_JoystickGetAxis_renamed_SDL_GetJoystickAxis +#define SDL_JoystickGetAxisInitialState SDL_JoystickGetAxisInitialState_renamed_SDL_GetJoystickAxisInitialState +#define SDL_JoystickGetBall SDL_JoystickGetBall_renamed_SDL_GetJoystickBall +#define SDL_JoystickGetButton SDL_JoystickGetButton_renamed_SDL_GetJoystickButton +#define SDL_JoystickGetFirmwareVersion SDL_JoystickGetFirmwareVersion_renamed_SDL_GetJoystickFirmwareVersion +#define SDL_JoystickGetGUID SDL_JoystickGetGUID_renamed_SDL_GetJoystickGUID +#define SDL_JoystickGetGUIDFromString SDL_JoystickGetGUIDFromString_renamed_SDL_GUIDFromString +#define SDL_JoystickGetHat SDL_JoystickGetHat_renamed_SDL_GetJoystickHat +#define SDL_JoystickGetPlayerIndex SDL_JoystickGetPlayerIndex_renamed_SDL_GetJoystickPlayerIndex +#define SDL_JoystickGetProduct SDL_JoystickGetProduct_renamed_SDL_GetJoystickProduct +#define SDL_JoystickGetProductVersion SDL_JoystickGetProductVersion_renamed_SDL_GetJoystickProductVersion +#define SDL_JoystickGetSerial SDL_JoystickGetSerial_renamed_SDL_GetJoystickSerial +#define SDL_JoystickGetType SDL_JoystickGetType_renamed_SDL_GetJoystickType +#define SDL_JoystickGetVendor SDL_JoystickGetVendor_renamed_SDL_GetJoystickVendor +#define SDL_JoystickInstanceID SDL_JoystickInstanceID_renamed_SDL_GetJoystickID +#define SDL_JoystickIsVirtual SDL_JoystickIsVirtual_renamed_SDL_IsJoystickVirtual +#define SDL_JoystickName SDL_JoystickName_renamed_SDL_GetJoystickName +#define SDL_JoystickNumAxes SDL_JoystickNumAxes_renamed_SDL_GetNumJoystickAxes +#define SDL_JoystickNumBalls SDL_JoystickNumBalls_renamed_SDL_GetNumJoystickBalls +#define SDL_JoystickNumButtons SDL_JoystickNumButtons_renamed_SDL_GetNumJoystickButtons +#define SDL_JoystickNumHats SDL_JoystickNumHats_renamed_SDL_GetNumJoystickHats +#define SDL_JoystickOpen SDL_JoystickOpen_renamed_SDL_OpenJoystick +#define SDL_JoystickPath SDL_JoystickPath_renamed_SDL_GetJoystickPath +#define SDL_JoystickRumble SDL_JoystickRumble_renamed_SDL_RumbleJoystick +#define SDL_JoystickRumbleTriggers SDL_JoystickRumbleTriggers_renamed_SDL_RumbleJoystickTriggers +#define SDL_JoystickSendEffect SDL_JoystickSendEffect_renamed_SDL_SendJoystickEffect +#define SDL_JoystickSetLED SDL_JoystickSetLED_renamed_SDL_SetJoystickLED +#define SDL_JoystickSetPlayerIndex SDL_JoystickSetPlayerIndex_renamed_SDL_SetJoystickPlayerIndex +#define SDL_JoystickSetVirtualAxis SDL_JoystickSetVirtualAxis_renamed_SDL_SetJoystickVirtualAxis +#define SDL_JoystickSetVirtualButton SDL_JoystickSetVirtualButton_renamed_SDL_SetJoystickVirtualButton +#define SDL_JoystickSetVirtualHat SDL_JoystickSetVirtualHat_renamed_SDL_SetJoystickVirtualHat +#define SDL_JoystickUpdate SDL_JoystickUpdate_renamed_SDL_UpdateJoysticks + +/* ##SDL_keyboard.h */ +#define SDL_IsScreenKeyboardShown SDL_IsScreenKeyboardShown_renamed_SDL_ScreenKeyboardShown +#define SDL_IsTextInputActive SDL_IsTextInputActive_renamed_SDL_TextInputActive + +/* ##SDL_keycode.h */ +#define KMOD_ALT KMOD_ALT_renamed_SDL_KMOD_ALT +#define KMOD_CAPS KMOD_CAPS_renamed_SDL_KMOD_CAPS +#define KMOD_CTRL KMOD_CTRL_renamed_SDL_KMOD_CTRL +#define KMOD_GUI KMOD_GUI_renamed_SDL_KMOD_GUI +#define KMOD_LALT KMOD_LALT_renamed_SDL_KMOD_LALT +#define KMOD_LCTRL KMOD_LCTRL_renamed_SDL_KMOD_LCTRL +#define KMOD_LGUI KMOD_LGUI_renamed_SDL_KMOD_LGUI +#define KMOD_LSHIFT KMOD_LSHIFT_renamed_SDL_KMOD_LSHIFT +#define KMOD_MODE KMOD_MODE_renamed_SDL_KMOD_MODE +#define KMOD_NONE KMOD_NONE_renamed_SDL_KMOD_NONE +#define KMOD_NUM KMOD_NUM_renamed_SDL_KMOD_NUM +#define KMOD_RALT KMOD_RALT_renamed_SDL_KMOD_RALT +#define KMOD_RCTRL KMOD_RCTRL_renamed_SDL_KMOD_RCTRL +#define KMOD_RGUI KMOD_RGUI_renamed_SDL_KMOD_RGUI +#define KMOD_RSHIFT KMOD_RSHIFT_renamed_SDL_KMOD_RSHIFT +#define KMOD_SCROLL KMOD_SCROLL_renamed_SDL_KMOD_SCROLL +#define KMOD_SHIFT KMOD_SHIFT_renamed_SDL_KMOD_SHIFT +#define SDLK_AUDIOFASTFORWARD SDLK_AUDIOFASTFORWARD_renamed_SDLK_MEDIA_FAST_FORWARD +#define SDLK_AUDIOMUTE SDLK_AUDIOMUTE_renamed_SDLK_MUTE +#define SDLK_AUDIONEXT SDLK_AUDIONEXT_renamed_SDLK_MEDIA_NEXT_TRACK +#define SDLK_AUDIOPLAY SDLK_AUDIOPLAY_renamed_SDLK_MEDIA_PLAY +#define SDLK_AUDIOPREV SDLK_AUDIOPREV_renamed_SDLK_MEDIA_PREVIOUS_TRACK +#define SDLK_AUDIOREWIND SDLK_AUDIOREWIND_renamed_SDLK_MEDIA_REWIND +#define SDLK_AUDIOSTOP SDLK_AUDIOSTOP_renamed_SDLK_MEDIA_STOP +#define SDLK_BACKQUOTE SDLK_BACKQUOTE_renamed_SDLK_GRAVE +#define SDLK_EJECT SDLK_EJECT_renamed_SDLK_MEDIA_EJECT +#define SDLK_MEDIASELECT SDLK_MEDIASELECT_renamed_SDLK_MEDIA_SELECT +#define SDLK_QUOTE SDLK_QUOTE_renamed_SDLK_APOSTROPHE +#define SDLK_QUOTEDBL SDLK_QUOTEDBL_renamed_SDLK_DBLAPOSTROPHE +#define SDLK_a SDLK_a_renamed_SDLK_A +#define SDLK_b SDLK_b_renamed_SDLK_B +#define SDLK_c SDLK_c_renamed_SDLK_C +#define SDLK_d SDLK_d_renamed_SDLK_D +#define SDLK_e SDLK_e_renamed_SDLK_E +#define SDLK_f SDLK_f_renamed_SDLK_F +#define SDLK_g SDLK_g_renamed_SDLK_G +#define SDLK_h SDLK_h_renamed_SDLK_H +#define SDLK_i SDLK_i_renamed_SDLK_I +#define SDLK_j SDLK_j_renamed_SDLK_J +#define SDLK_k SDLK_k_renamed_SDLK_K +#define SDLK_l SDLK_l_renamed_SDLK_L +#define SDLK_m SDLK_m_renamed_SDLK_M +#define SDLK_n SDLK_n_renamed_SDLK_N +#define SDLK_o SDLK_o_renamed_SDLK_O +#define SDLK_p SDLK_p_renamed_SDLK_P +#define SDLK_q SDLK_q_renamed_SDLK_Q +#define SDLK_r SDLK_r_renamed_SDLK_R +#define SDLK_s SDLK_s_renamed_SDLK_S +#define SDLK_t SDLK_t_renamed_SDLK_T +#define SDLK_u SDLK_u_renamed_SDLK_U +#define SDLK_v SDLK_v_renamed_SDLK_V +#define SDLK_w SDLK_w_renamed_SDLK_W +#define SDLK_x SDLK_x_renamed_SDLK_X +#define SDLK_y SDLK_y_renamed_SDLK_Y +#define SDLK_z SDLK_z_renamed_SDLK_Z + +/* ##SDL_log.h */ +#define SDL_LogGetOutputFunction SDL_LogGetOutputFunction_renamed_SDL_GetLogOutputFunction +#define SDL_LogGetPriority SDL_LogGetPriority_renamed_SDL_GetLogPriority +#define SDL_LogResetPriorities SDL_LogResetPriorities_renamed_SDL_ResetLogPriorities +#define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities +#define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction +#define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT + +/* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK +#define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT +#define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT +#define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER +#define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT +#define SDL_SYSTEM_CURSOR_NO SDL_SYSTEM_CURSOR_NO_renamed_SDL_SYSTEM_CURSOR_NOT_ALLOWED +#define SDL_SYSTEM_CURSOR_SIZEALL SDL_SYSTEM_CURSOR_SIZEALL_renamed_SDL_SYSTEM_CURSOR_MOVE +#define SDL_SYSTEM_CURSOR_SIZENESW SDL_SYSTEM_CURSOR_SIZENESW_renamed_SDL_SYSTEM_CURSOR_NESW_RESIZE +#define SDL_SYSTEM_CURSOR_SIZENS SDL_SYSTEM_CURSOR_SIZENS_renamed_SDL_SYSTEM_CURSOR_NS_RESIZE +#define SDL_SYSTEM_CURSOR_SIZENWSE SDL_SYSTEM_CURSOR_SIZENWSE_renamed_SDL_SYSTEM_CURSOR_NWSE_RESIZE +#define SDL_SYSTEM_CURSOR_SIZEWE SDL_SYSTEM_CURSOR_SIZEWE_renamed_SDL_SYSTEM_CURSOR_EW_RESIZE +#define SDL_SYSTEM_CURSOR_WAITARROW SDL_SYSTEM_CURSOR_WAITARROW_renamed_SDL_SYSTEM_CURSOR_PROGRESS +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOM SDL_SYSTEM_CURSOR_WINDOW_BOTTOM_renamed_SDL_SYSTEM_CURSOR_S_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOMLEFT SDL_SYSTEM_CURSOR_WINDOW_BOTTOMLEFT_renamed_SDL_SYSTEM_CURSOR_SW_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_BOTTOMRIGHT SDL_SYSTEM_CURSOR_WINDOW_BOTTOMRIGHT_renamed_SDL_SYSTEM_CURSOR_SE_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_LEFT SDL_SYSTEM_CURSOR_WINDOW_LEFT_renamed_SDL_SYSTEM_CURSOR_W_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_RIGHT SDL_SYSTEM_CURSOR_WINDOW_RIGHT_renamed_SDL_SYSTEM_CURSOR_E_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOP SDL_SYSTEM_CURSOR_WINDOW_TOP_renamed_SDL_SYSTEM_CURSOR_N_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOPLEFT SDL_SYSTEM_CURSOR_WINDOW_TOPLEFT_renamed_SDL_SYSTEM_CURSOR_NW_RESIZE +#define SDL_SYSTEM_CURSOR_WINDOW_TOPRIGHT SDL_SYSTEM_CURSOR_WINDOW_TOPRIGHT_renamed_SDL_SYSTEM_CURSOR_NE_RESIZE + +/* ##SDL_mutex.h */ +#define SDL_CondBroadcast SDL_CondBroadcast_renamed_SDL_BroadcastCondition +#define SDL_CondSignal SDL_CondSignal_renamed_SDL_SignalCondition +#define SDL_CondWait SDL_CondWait_renamed_SDL_WaitCondition +#define SDL_CondWaitTimeout SDL_CondWaitTimeout_renamed_SDL_WaitConditionTimeout +#define SDL_CreateCond SDL_CreateCond_renamed_SDL_CreateCondition +#define SDL_DestroyCond SDL_DestroyCond_renamed_SDL_DestroyCondition +#define SDL_SemPost SDL_SemPost_renamed_SDL_SignalSemaphore +#define SDL_SemTryWait SDL_SemTryWait_renamed_SDL_TryWaitSemaphore +#define SDL_SemValue SDL_SemValue_renamed_SDL_GetSemaphoreValue +#define SDL_SemWait SDL_SemWait_renamed_SDL_WaitSemaphore +#define SDL_SemWaitTimeout SDL_SemWaitTimeout_renamed_SDL_WaitSemaphoreTimeout + +/* ##SDL_mutex.h */ +#define SDL_cond SDL_cond_renamed_SDL_Condition +#define SDL_mutex SDL_mutex_renamed_SDL_Mutex +#define SDL_sem SDL_sem_renamed_SDL_Semaphore + +/* ##SDL_pixels.h */ +#define SDL_AllocFormat SDL_AllocFormat_renamed_SDL_GetPixelFormatDetails +#define SDL_AllocPalette SDL_AllocPalette_renamed_SDL_CreatePalette +#define SDL_Colour SDL_Colour_renamed_SDL_Color +#define SDL_FreePalette SDL_FreePalette_renamed_SDL_DestroyPalette +#define SDL_MasksToPixelFormatEnum SDL_MasksToPixelFormatEnum_renamed_SDL_GetPixelFormatForMasks +#define SDL_PIXELFORMAT_BGR444 SDL_PIXELFORMAT_BGR444_renamed_SDL_PIXELFORMAT_XBGR4444 +#define SDL_PIXELFORMAT_BGR555 SDL_PIXELFORMAT_BGR555_renamed_SDL_PIXELFORMAT_XBGR1555 +#define SDL_PIXELFORMAT_BGR888 SDL_PIXELFORMAT_BGR888_renamed_SDL_PIXELFORMAT_XBGR8888 +#define SDL_PIXELFORMAT_RGB444 SDL_PIXELFORMAT_RGB444_renamed_SDL_PIXELFORMAT_XRGB4444 +#define SDL_PIXELFORMAT_RGB555 SDL_PIXELFORMAT_RGB555_renamed_SDL_PIXELFORMAT_XRGB1555 +#define SDL_PIXELFORMAT_RGB888 SDL_PIXELFORMAT_RGB888_renamed_SDL_PIXELFORMAT_XRGB8888 +#define SDL_PixelFormatEnumToMasks SDL_PixelFormatEnumToMasks_renamed_SDL_GetMasksForPixelFormat + +/* ##SDL_rect.h */ +#define SDL_EncloseFPoints SDL_EncloseFPoints_renamed_SDL_GetRectEnclosingPointsFloat +#define SDL_EnclosePoints SDL_EnclosePoints_renamed_SDL_GetRectEnclosingPoints +#define SDL_FRectEmpty SDL_FRectEmpty_renamed_SDL_RectEmptyFloat +#define SDL_FRectEquals SDL_FRectEquals_renamed_SDL_RectsEqualFloat +#define SDL_FRectEqualsEpsilon SDL_FRectEqualsEpsilon_renamed_SDL_RectsEqualEpsilon +#define SDL_HasIntersection SDL_HasIntersection_renamed_SDL_HasRectIntersection +#define SDL_HasIntersectionF SDL_HasIntersectionF_renamed_SDL_HasRectIntersectionFloat +#define SDL_IntersectFRect SDL_IntersectFRect_renamed_SDL_GetRectIntersectionFloat +#define SDL_IntersectFRectAndLine SDL_IntersectFRectAndLine_renamed_SDL_GetRectAndLineIntersectionFloat +#define SDL_IntersectRect SDL_IntersectRect_renamed_SDL_GetRectIntersection +#define SDL_IntersectRectAndLine SDL_IntersectRectAndLine_renamed_SDL_GetRectAndLineIntersection +#define SDL_PointInFRect SDL_PointInFRect_renamed_SDL_PointInRectFloat +#define SDL_RectEquals SDL_RectEquals_renamed_SDL_RectsEqual +#define SDL_UnionFRect SDL_UnionFRect_renamed_SDL_GetRectUnionFloat +#define SDL_UnionRect SDL_UnionRect_renamed_SDL_GetRectUnion + +/* ##SDL_render.h */ +#define SDL_GetRendererOutputSize SDL_GetRendererOutputSize_renamed_SDL_GetCurrentRenderOutputSize +#define SDL_RenderCopy SDL_RenderCopy_renamed_SDL_RenderTexture +#define SDL_RenderCopyEx SDL_RenderCopyEx_renamed_SDL_RenderTextureRotated +#define SDL_RenderCopyExF SDL_RenderCopyExF_renamed_SDL_RenderTextureRotated +#define SDL_RenderCopyF SDL_RenderCopyF_renamed_SDL_RenderTexture +#define SDL_RenderDrawLine SDL_RenderDrawLine_renamed_SDL_RenderLine +#define SDL_RenderDrawLineF SDL_RenderDrawLineF_renamed_SDL_RenderLine +#define SDL_RenderDrawLines SDL_RenderDrawLines_renamed_SDL_RenderLines +#define SDL_RenderDrawLinesF SDL_RenderDrawLinesF_renamed_SDL_RenderLines +#define SDL_RenderDrawPoint SDL_RenderDrawPoint_renamed_SDL_RenderPoint +#define SDL_RenderDrawPointF SDL_RenderDrawPointF_renamed_SDL_RenderPoint +#define SDL_RenderDrawPoints SDL_RenderDrawPoints_renamed_SDL_RenderPoints +#define SDL_RenderDrawPointsF SDL_RenderDrawPointsF_renamed_SDL_RenderPoints +#define SDL_RenderDrawRect SDL_RenderDrawRect_renamed_SDL_RenderRect +#define SDL_RenderDrawRectF SDL_RenderDrawRectF_renamed_SDL_RenderRect +#define SDL_RenderDrawRects SDL_RenderDrawRects_renamed_SDL_RenderRects +#define SDL_RenderDrawRectsF SDL_RenderDrawRectsF_renamed_SDL_RenderRects +#define SDL_RenderFillRectF SDL_RenderFillRectF_renamed_SDL_RenderFillRect +#define SDL_RenderFillRectsF SDL_RenderFillRectsF_renamed_SDL_RenderFillRects +#define SDL_RendererFlip SDL_RendererFlip_renamed_SDL_FlipMode +#define SDL_RenderFlush SDL_RenderFlush_renamed_SDL_FlushRenderer +#define SDL_RenderGetClipRect SDL_RenderGetClipRect_renamed_SDL_GetRenderClipRect +#define SDL_RenderGetLogicalSize SDL_RenderGetLogicalSize_renamed_SDL_GetRenderLogicalPresentation +#define SDL_RenderGetMetalCommandEncoder SDL_RenderGetMetalCommandEncoder_renamed_SDL_GetRenderMetalCommandEncoder +#define SDL_RenderGetMetalLayer SDL_RenderGetMetalLayer_renamed_SDL_GetRenderMetalLayer +#define SDL_RenderGetScale SDL_RenderGetScale_renamed_SDL_GetRenderScale +#define SDL_RenderGetViewport SDL_RenderGetViewport_renamed_SDL_GetRenderViewport +#define SDL_RenderGetWindow SDL_RenderGetWindow_renamed_SDL_GetRenderWindow +#define SDL_RenderIsClipEnabled SDL_RenderIsClipEnabled_renamed_SDL_RenderClipEnabled +#define SDL_RenderLogicalToWindow SDL_RenderLogicalToWindow_renamed_SDL_RenderCoordinatesToWindow +#define SDL_RenderSetClipRect SDL_RenderSetClipRect_renamed_SDL_SetRenderClipRect +#define SDL_RenderSetLogicalSize SDL_RenderSetLogicalSize_renamed_SDL_SetRenderLogicalPresentation +#define SDL_RenderSetScale SDL_RenderSetScale_renamed_SDL_SetRenderScale +#define SDL_RenderSetVSync SDL_RenderSetVSync_renamed_SDL_SetRenderVSync +#define SDL_RenderSetViewport SDL_RenderSetViewport_renamed_SDL_SetRenderViewport +#define SDL_RenderWindowToLogical SDL_RenderWindowToLogical_renamed_SDL_RenderCoordinatesFromWindow +#define SDL_ScaleModeLinear SDL_ScaleModeLinear_renamed_SDL_SCALEMODE_LINEAR +#define SDL_ScaleModeNearest SDL_ScaleModeNearest_renamed_SDL_SCALEMODE_NEAREST + +/* ##SDL_rwops.h */ +#define RW_SEEK_CUR RW_SEEK_CUR_renamed_SDL_IO_SEEK_CUR +#define RW_SEEK_END RW_SEEK_END_renamed_SDL_IO_SEEK_END +#define RW_SEEK_SET RW_SEEK_SET_renamed_SDL_IO_SEEK_SET +#define SDL_RWFromConstMem SDL_RWFromConstMem_renamed_SDL_IOFromConstMem +#define SDL_RWFromFile SDL_RWFromFile_renamed_SDL_IOFromFile +#define SDL_RWFromMem SDL_RWFromMem_renamed_SDL_IOFromMem +#define SDL_RWclose SDL_RWclose_renamed_SDL_CloseIO +#define SDL_RWops SDL_RWops_renamed_SDL_IOStream +#define SDL_RWread SDL_RWread_renamed_SDL_ReadIO +#define SDL_RWseek SDL_RWseek_renamed_SDL_SeekIO +#define SDL_RWsize SDL_RWsize_renamed_SDL_GetIOSize +#define SDL_RWtell SDL_RWtell_renamed_SDL_TellIO +#define SDL_RWwrite SDL_RWwrite_renamed_SDL_WriteIO +#define SDL_ReadBE16 SDL_ReadBE16_renamed_SDL_ReadU16BE +#define SDL_ReadBE32 SDL_ReadBE32_renamed_SDL_ReadU32BE +#define SDL_ReadBE64 SDL_ReadBE64_renamed_SDL_ReadU64BE +#define SDL_ReadLE16 SDL_ReadLE16_renamed_SDL_ReadU16LE +#define SDL_ReadLE32 SDL_ReadLE32_renamed_SDL_ReadU32LE +#define SDL_ReadLE64 SDL_ReadLE64_renamed_SDL_ReadU64LE +#define SDL_WriteBE16 SDL_WriteBE16_renamed_SDL_WriteU16BE +#define SDL_WriteBE32 SDL_WriteBE32_renamed_SDL_WriteU32BE +#define SDL_WriteBE64 SDL_WriteBE64_renamed_SDL_WriteU64BE +#define SDL_WriteLE16 SDL_WriteLE16_renamed_SDL_WriteU16LE +#define SDL_WriteLE32 SDL_WriteLE32_renamed_SDL_WriteU32LE +#define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE + +/* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT +#define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD +#define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE +#define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK +#define SDL_SCANCODE_AUDIOPLAY SDL_SCANCODE_AUDIOPLAY_renamed_SDL_SCANCODE_MEDIA_PLAY +#define SDL_SCANCODE_AUDIOPREV SDL_SCANCODE_AUDIOPREV_renamed_SDL_SCANCODE_MEDIA_PREVIOUS_TRACK +#define SDL_SCANCODE_AUDIOREWIND SDL_SCANCODE_AUDIOREWIND_renamed_SDL_SCANCODE_MEDIA_REWIND +#define SDL_SCANCODE_AUDIOSTOP SDL_SCANCODE_AUDIOSTOP_renamed_SDL_SCANCODE_MEDIA_STOP +#define SDL_SCANCODE_EJECT SDL_SCANCODE_EJECT_renamed_SDL_SCANCODE_MEDIA_EJECT +#define SDL_SCANCODE_MEDIASELECT SDL_SCANCODE_MEDIASELECT_renamed_SDL_SCANCODE_MEDIA_SELECT + +/* ##SDL_sensor.h */ +#define SDL_SensorClose SDL_SensorClose_renamed_SDL_CloseSensor +#define SDL_SensorFromInstanceID SDL_SensorFromInstanceID_renamed_SDL_GetSensorFromID +#define SDL_SensorGetData SDL_SensorGetData_renamed_SDL_GetSensorData +#define SDL_SensorGetInstanceID SDL_SensorGetInstanceID_renamed_SDL_GetSensorID +#define SDL_SensorGetName SDL_SensorGetName_renamed_SDL_GetSensorName +#define SDL_SensorGetNonPortableType SDL_SensorGetNonPortableType_renamed_SDL_GetSensorNonPortableType +#define SDL_SensorGetType SDL_SensorGetType_renamed_SDL_GetSensorType +#define SDL_SensorOpen SDL_SensorOpen_renamed_SDL_OpenSensor +#define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors + +/* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false +#define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow +#define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r + +/* ##SDL_surface.h */ +#define SDL_BlitScaled SDL_BlitScaled_renamed_SDL_BlitSurfaceScaled +#define SDL_ConvertSurfaceFormat SDL_ConvertSurfaceFormat_renamed_SDL_ConvertSurface +#define SDL_FillRect SDL_FillRect_renamed_SDL_FillSurfaceRect +#define SDL_FillRects SDL_FillRects_renamed_SDL_FillSurfaceRects +#define SDL_FreeSurface SDL_FreeSurface_renamed_SDL_DestroySurface +#define SDL_GetClipRect SDL_GetClipRect_renamed_SDL_GetSurfaceClipRect +#define SDL_GetColorKey SDL_GetColorKey_renamed_SDL_GetSurfaceColorKey +#define SDL_HasColorKey SDL_HasColorKey_renamed_SDL_SurfaceHasColorKey +#define SDL_HasSurfaceRLE SDL_HasSurfaceRLE_renamed_SDL_SurfaceHasRLE +#define SDL_LoadBMP_RW SDL_LoadBMP_RW_renamed_SDL_LoadBMP_IO +#define SDL_LowerBlit SDL_LowerBlit_renamed_SDL_BlitSurfaceUnchecked +#define SDL_LowerBlitScaled SDL_LowerBlitScaled_renamed_SDL_BlitSurfaceUncheckedScaled +#define SDL_PREALLOC SDL_PREALLOC_renamed_SDL_SURFACE_PREALLOCATED +#define SDL_SIMD_ALIGNED SDL_SIMD_ALIGNED_renamed_SDL_SURFACE_SIMD_ALIGNED +#define SDL_SaveBMP_RW SDL_SaveBMP_RW_renamed_SDL_SaveBMP_IO +#define SDL_SetClipRect SDL_SetClipRect_renamed_SDL_SetSurfaceClipRect +#define SDL_SetColorKey SDL_SetColorKey_renamed_SDL_SetSurfaceColorKey +#define SDL_UpperBlit SDL_UpperBlit_renamed_SDL_BlitSurface +#define SDL_UpperBlitScaled SDL_UpperBlitScaled_renamed_SDL_BlitSurfaceScaled + +/* ##SDL_system.h */ +#define SDL_AndroidBackButton SDL_AndroidBackButton_renamed_SDL_SendAndroidBackButton +#define SDL_AndroidGetActivity SDL_AndroidGetActivity_renamed_SDL_GetAndroidActivity +#define SDL_AndroidGetExternalStoragePath SDL_AndroidGetExternalStoragePath_renamed_SDL_GetAndroidExternalStoragePath +#define SDL_AndroidGetExternalStorageState SDL_AndroidGetExternalStorageState_renamed_SDL_GetAndroidExternalStorageState +#define SDL_AndroidGetInternalStoragePath SDL_AndroidGetInternalStoragePath_renamed_SDL_GetAndroidInternalStoragePath +#define SDL_AndroidGetJNIEnv SDL_AndroidGetJNIEnv_renamed_SDL_GetAndroidJNIEnv +#define SDL_AndroidRequestPermission SDL_AndroidRequestPermission_renamed_SDL_RequestAndroidPermission +#define SDL_AndroidRequestPermissionCallback SDL_AndroidRequestPermissionCallback_renamed_SDL_RequestAndroidPermissionCallback +#define SDL_AndroidSendMessage SDL_AndroidSendMessage_renamed_SDL_SendAndroidMessage +#define SDL_AndroidShowToast SDL_AndroidShowToast_renamed_SDL_ShowAndroidToast +#define SDL_DXGIGetOutputInfo SDL_DXGIGetOutputInfo_renamed_SDL_GetDXGIOutputInfo +#define SDL_Direct3D9GetAdapterIndex SDL_Direct3D9GetAdapterIndex_renamed_SDL_GetDirect3D9AdapterIndex +#define SDL_GDKGetDefaultUser SDL_GDKGetDefaultUser_renamed_SDL_GetGDKDefaultUser +#define SDL_GDKGetTaskQueue SDL_GDKGetTaskQueue_renamed_SDL_GetGDKTaskQueue +#define SDL_LinuxSetThreadPriority SDL_LinuxSetThreadPriority_renamed_SDL_SetLinuxThreadPriority +#define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy +#define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground +#define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground +#define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback +#define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump +#define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback +#define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump + +/* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority +#define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS +#define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS +#define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS +#define SDL_threadID SDL_threadID_renamed_SDL_ThreadID + +/* ##SDL_timer.h */ +#define SDL_GetTicks64 SDL_GetTicks64_renamed_SDL_GetTicks + +/* ##SDL_version.h */ +#define SDL_COMPILEDVERSION SDL_COMPILEDVERSION_renamed_SDL_VERSION +#define SDL_PATCHLEVEL SDL_PATCHLEVEL_renamed_SDL_MICRO_VERSION + +/* ##SDL_video.h */ +#define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile +#define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode +#define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation +#define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint +#define SDL_GetRectDisplayIndex SDL_GetRectDisplayIndex_renamed_SDL_GetDisplayForRect +#define SDL_GetWindowDisplayIndex SDL_GetWindowDisplayIndex_renamed_SDL_GetDisplayForWindow +#define SDL_GetWindowDisplayMode SDL_GetWindowDisplayMode_renamed_SDL_GetWindowFullscreenMode +#define SDL_HasWindowSurface SDL_HasWindowSurface_renamed_SDL_WindowHasSurface +#define SDL_IsScreenSaverEnabled SDL_IsScreenSaverEnabled_renamed_SDL_ScreenSaverEnabled +#define SDL_SetWindowDisplayMode SDL_SetWindowDisplayMode_renamed_SDL_SetWindowFullscreenMode +#define SDL_WINDOW_ALLOW_HIGHDPI SDL_WINDOW_ALLOW_HIGHDPI_renamed_SDL_WINDOW_HIGH_PIXEL_DENSITY +#define SDL_WINDOW_INPUT_GRABBED SDL_WINDOW_INPUT_GRABBED_renamed_SDL_WINDOW_MOUSE_GRABBED +#define SDL_WINDOW_SKIP_TASKBAR SDL_WINDOW_SKIP_TASKBAR_renamed_SDL_WINDOW_UTILITY + +#endif /* SDL_ENABLE_OLD_NAMES */ + +#endif /* SDL_oldnames_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengl.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl.h similarity index 63% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengl.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl.h index c6250d131b..d1b8b02a37 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_opengl.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl.h @@ -29,9 +29,9 @@ #ifndef SDL_opengl_h_ #define SDL_opengl_h_ -#include "SDL_config.h" +#include -#ifndef __IPHONEOS__ /* No OpenGL on iOS. */ +#ifndef SDL_PLATFORM_IOS /* No OpenGL on iOS. */ /* * Mesa 3-D graphics library @@ -62,8 +62,8 @@ #ifndef __gl_h_ #define __gl_h_ -#if defined(USE_MGL_NAMESPACE) -#include "gl_mangle.h" +#ifdef USE_MGL_NAMESPACE +#include #endif @@ -71,11 +71,7 @@ * Begin system-specific stuff. */ -#if defined(_WIN32) && !defined(__WIN32__) && !defined(__CYGWIN__) -#define __WIN32__ -#endif - -#if defined(__WIN32__) && !defined(__CYGWIN__) +#if defined(_WIN32) && !defined(__CYGWIN__) # if (defined(_MSC_VER) || defined(__MINGW32__)) && defined(BUILD_GL32) /* tag specify we're building mesa as a DLL */ # define GLAPI __declspec(dllexport) # elif (defined(_MSC_VER) || defined(__MINGW32__)) && defined(_DLL) /* tag specifying we're building for DLL runtime support */ @@ -84,20 +80,13 @@ # define GLAPI extern # endif /* _STATIC_MESA support */ # if defined(__MINGW32__) && defined(GL_NO_STDCALL) || defined(UNDER_CE) /* The generated DLLs by MingW with STDCALL are not compatible with the ones done by Microsoft's compilers */ -# define GLAPIENTRY +# define GLAPIENTRY # else # define GLAPIENTRY __stdcall # endif #elif defined(__CYGWIN__) && defined(USE_OPENGL32) /* use native windows opengl32 */ # define GLAPI extern # define GLAPIENTRY __stdcall -#elif defined(__OS2__) || defined(__EMX__) /* native os/2 opengl */ -# define GLAPI extern -# define GLAPIENTRY _System -# define APIENTRY _System -# if defined(__GNUC__) && !defined(_System) -# define _System -# endif #elif (defined(__GNUC__) && __GNUC__ >= 4) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x590)) # define GLAPI __attribute__((visibility("default"))) # define GLAPIENTRY @@ -794,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1491,309 +1481,1154 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); -/* - * OpenGL 1.2 - */ +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); -#define GL_RESCALE_NORMAL 0x803A -#define GL_CLAMP_TO_EDGE 0x812F -#define GL_MAX_ELEMENTS_VERTICES 0x80E8 -#define GL_MAX_ELEMENTS_INDICES 0x80E9 -#define GL_BGR 0x80E0 -#define GL_BGRA 0x80E1 -#define GL_UNSIGNED_BYTE_3_3_2 0x8032 -#define GL_UNSIGNED_BYTE_2_3_3_REV 0x8362 -#define GL_UNSIGNED_SHORT_5_6_5 0x8363 -#define GL_UNSIGNED_SHORT_5_6_5_REV 0x8364 -#define GL_UNSIGNED_SHORT_4_4_4_4 0x8033 -#define GL_UNSIGNED_SHORT_4_4_4_4_REV 0x8365 -#define GL_UNSIGNED_SHORT_5_5_5_1 0x8034 -#define GL_UNSIGNED_SHORT_1_5_5_5_REV 0x8366 -#define GL_UNSIGNED_INT_8_8_8_8 0x8035 -#define GL_UNSIGNED_INT_8_8_8_8_REV 0x8367 -#define GL_UNSIGNED_INT_10_10_10_2 0x8036 -#define GL_UNSIGNED_INT_2_10_10_10_REV 0x8368 -#define GL_LIGHT_MODEL_COLOR_CONTROL 0x81F8 -#define GL_SINGLE_COLOR 0x81F9 -#define GL_SEPARATE_SPECULAR_COLOR 0x81FA -#define GL_TEXTURE_MIN_LOD 0x813A -#define GL_TEXTURE_MAX_LOD 0x813B -#define GL_TEXTURE_BASE_LEVEL 0x813C -#define GL_TEXTURE_MAX_LEVEL 0x813D -#define GL_SMOOTH_POINT_SIZE_RANGE 0x0B12 -#define GL_SMOOTH_POINT_SIZE_GRANULARITY 0x0B13 -#define GL_SMOOTH_LINE_WIDTH_RANGE 0x0B22 -#define GL_SMOOTH_LINE_WIDTH_GRANULARITY 0x0B23 -#define GL_ALIASED_POINT_SIZE_RANGE 0x846D -#define GL_ALIASED_LINE_WIDTH_RANGE 0x846E -#define GL_PACK_SKIP_IMAGES 0x806B -#define GL_PACK_IMAGE_HEIGHT 0x806C -#define GL_UNPACK_SKIP_IMAGES 0x806D -#define GL_UNPACK_IMAGE_HEIGHT 0x806E -#define GL_TEXTURE_3D 0x806F -#define GL_PROXY_TEXTURE_3D 0x8070 -#define GL_TEXTURE_DEPTH 0x8071 -#define GL_TEXTURE_WRAP_R 0x8072 -#define GL_MAX_3D_TEXTURE_SIZE 0x8073 -#define GL_TEXTURE_BINDING_3D 0x806A +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); -GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, - GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); -GLAPI void GLAPIENTRY glTexImage3D( GLenum target, GLint level, - GLint internalFormat, - GLsizei width, GLsizei height, - GLsizei depth, GLint border, - GLenum format, GLenum type, - const GLvoid *pixels ); +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); -GLAPI void GLAPIENTRY glTexSubImage3D( GLenum target, GLint level, - GLint xoffset, GLint yoffset, - GLint zoffset, GLsizei width, - GLsizei height, GLsizei depth, - GLenum format, - GLenum type, const GLvoid *pixels); +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); -GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, - GLint xoffset, GLint yoffset, - GLint zoffset, GLint x, - GLint y, GLsizei width, - GLsizei height ); +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); -typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); -typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); -typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); -typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLint x, GLint y, GLsizei width, GLsizei height); +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); -/* - * GL_ARB_imaging - */ +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); -#define GL_CONSTANT_COLOR 0x8001 -#define GL_ONE_MINUS_CONSTANT_COLOR 0x8002 -#define GL_CONSTANT_ALPHA 0x8003 -#define GL_ONE_MINUS_CONSTANT_ALPHA 0x8004 -#define GL_COLOR_TABLE 0x80D0 -#define GL_POST_CONVOLUTION_COLOR_TABLE 0x80D1 -#define GL_POST_COLOR_MATRIX_COLOR_TABLE 0x80D2 -#define GL_PROXY_COLOR_TABLE 0x80D3 -#define GL_PROXY_POST_CONVOLUTION_COLOR_TABLE 0x80D4 -#define GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE 0x80D5 -#define GL_COLOR_TABLE_SCALE 0x80D6 -#define GL_COLOR_TABLE_BIAS 0x80D7 -#define GL_COLOR_TABLE_FORMAT 0x80D8 -#define GL_COLOR_TABLE_WIDTH 0x80D9 -#define GL_COLOR_TABLE_RED_SIZE 0x80DA -#define GL_COLOR_TABLE_GREEN_SIZE 0x80DB -#define GL_COLOR_TABLE_BLUE_SIZE 0x80DC -#define GL_COLOR_TABLE_ALPHA_SIZE 0x80DD -#define GL_COLOR_TABLE_LUMINANCE_SIZE 0x80DE -#define GL_COLOR_TABLE_INTENSITY_SIZE 0x80DF -#define GL_CONVOLUTION_1D 0x8010 -#define GL_CONVOLUTION_2D 0x8011 -#define GL_SEPARABLE_2D 0x8012 -#define GL_CONVOLUTION_BORDER_MODE 0x8013 -#define GL_CONVOLUTION_FILTER_SCALE 0x8014 -#define GL_CONVOLUTION_FILTER_BIAS 0x8015 -#define GL_REDUCE 0x8016 -#define GL_CONVOLUTION_FORMAT 0x8017 -#define GL_CONVOLUTION_WIDTH 0x8018 -#define GL_CONVOLUTION_HEIGHT 0x8019 -#define GL_MAX_CONVOLUTION_WIDTH 0x801A -#define GL_MAX_CONVOLUTION_HEIGHT 0x801B -#define GL_POST_CONVOLUTION_RED_SCALE 0x801C -#define GL_POST_CONVOLUTION_GREEN_SCALE 0x801D -#define GL_POST_CONVOLUTION_BLUE_SCALE 0x801E -#define GL_POST_CONVOLUTION_ALPHA_SCALE 0x801F -#define GL_POST_CONVOLUTION_RED_BIAS 0x8020 -#define GL_POST_CONVOLUTION_GREEN_BIAS 0x8021 -#define GL_POST_CONVOLUTION_BLUE_BIAS 0x8022 -#define GL_POST_CONVOLUTION_ALPHA_BIAS 0x8023 -#define GL_CONSTANT_BORDER 0x8151 -#define GL_REPLICATE_BORDER 0x8153 -#define GL_CONVOLUTION_BORDER_COLOR 0x8154 -#define GL_COLOR_MATRIX 0x80B1 -#define GL_COLOR_MATRIX_STACK_DEPTH 0x80B2 -#define GL_MAX_COLOR_MATRIX_STACK_DEPTH 0x80B3 -#define GL_POST_COLOR_MATRIX_RED_SCALE 0x80B4 -#define GL_POST_COLOR_MATRIX_GREEN_SCALE 0x80B5 -#define GL_POST_COLOR_MATRIX_BLUE_SCALE 0x80B6 -#define GL_POST_COLOR_MATRIX_ALPHA_SCALE 0x80B7 -#define GL_POST_COLOR_MATRIX_RED_BIAS 0x80B8 -#define GL_POST_COLOR_MATRIX_GREEN_BIAS 0x80B9 -#define GL_POST_COLOR_MATRIX_BLUE_BIAS 0x80BA -#define GL_POST_COLOR_MATRIX_ALPHA_BIAS 0x80BB -#define GL_HISTOGRAM 0x8024 -#define GL_PROXY_HISTOGRAM 0x8025 -#define GL_HISTOGRAM_WIDTH 0x8026 -#define GL_HISTOGRAM_FORMAT 0x8027 -#define GL_HISTOGRAM_RED_SIZE 0x8028 -#define GL_HISTOGRAM_GREEN_SIZE 0x8029 -#define GL_HISTOGRAM_BLUE_SIZE 0x802A -#define GL_HISTOGRAM_ALPHA_SIZE 0x802B -#define GL_HISTOGRAM_LUMINANCE_SIZE 0x802C -#define GL_HISTOGRAM_SINK 0x802D -#define GL_MINMAX 0x802E -#define GL_MINMAX_FORMAT 0x802F -#define GL_MINMAX_SINK 0x8030 -#define GL_TABLE_TOO_LARGE 0x8031 -#define GL_BLEND_EQUATION 0x8009 -#define GL_MIN 0x8007 -#define GL_MAX 0x8008 -#define GL_FUNC_ADD 0x8006 -#define GL_FUNC_SUBTRACT 0x800A -#define GL_FUNC_REVERSE_SUBTRACT 0x800B -#define GL_BLEND_COLOR 0x8005 +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); -GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, - GLsizei width, GLenum format, - GLenum type, const GLvoid *table ); +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); -GLAPI void GLAPIENTRY glColorSubTable( GLenum target, - GLsizei start, GLsizei count, - GLenum format, GLenum type, - const GLvoid *data ); +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); -GLAPI void GLAPIENTRY glColorTableParameteriv(GLenum target, GLenum pname, - const GLint *params); +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); -GLAPI void GLAPIENTRY glColorTableParameterfv(GLenum target, GLenum pname, - const GLfloat *params); +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); -GLAPI void GLAPIENTRY glCopyColorSubTable( GLenum target, GLsizei start, - GLint x, GLint y, GLsizei width ); +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); -GLAPI void GLAPIENTRY glCopyColorTable( GLenum target, GLenum internalformat, - GLint x, GLint y, GLsizei width ); +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); -GLAPI void GLAPIENTRY glGetColorTable( GLenum target, GLenum format, - GLenum type, GLvoid *table ); +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); -GLAPI void GLAPIENTRY glGetColorTableParameterfv( GLenum target, GLenum pname, - GLfloat *params ); +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); -GLAPI void GLAPIENTRY glGetColorTableParameteriv( GLenum target, GLenum pname, - GLint *params ); +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); -GLAPI void GLAPIENTRY glBlendEquation( GLenum mode ); +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); -GLAPI void GLAPIENTRY glBlendColor( GLclampf red, GLclampf green, - GLclampf blue, GLclampf alpha ); +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); -GLAPI void GLAPIENTRY glHistogram( GLenum target, GLsizei width, - GLenum internalformat, GLboolean sink ); +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); -GLAPI void GLAPIENTRY glResetHistogram( GLenum target ); +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); -GLAPI void GLAPIENTRY glGetHistogram( GLenum target, GLboolean reset, - GLenum format, GLenum type, - GLvoid *values ); +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); -GLAPI void GLAPIENTRY glGetHistogramParameterfv( GLenum target, GLenum pname, - GLfloat *params ); +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); -GLAPI void GLAPIENTRY glGetHistogramParameteriv( GLenum target, GLenum pname, - GLint *params ); -GLAPI void GLAPIENTRY glMinmax( GLenum target, GLenum internalformat, - GLboolean sink ); +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ -GLAPI void GLAPIENTRY glResetMinmax( GLenum target ); +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ -GLAPI void GLAPIENTRY glGetMinmax( GLenum target, GLboolean reset, - GLenum format, GLenum types, - GLvoid *values ); -GLAPI void GLAPIENTRY glGetMinmaxParameterfv( GLenum target, GLenum pname, - GLfloat *params ); +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); -GLAPI void GLAPIENTRY glGetMinmaxParameteriv( GLenum target, GLenum pname, - GLint *params ); +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); -GLAPI void GLAPIENTRY glConvolutionFilter1D( GLenum target, - GLenum internalformat, GLsizei width, GLenum format, GLenum type, - const GLvoid *image ); +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); -GLAPI void GLAPIENTRY glConvolutionFilter2D( GLenum target, - GLenum internalformat, GLsizei width, GLsizei height, GLenum format, - GLenum type, const GLvoid *image ); +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); -GLAPI void GLAPIENTRY glConvolutionParameterf( GLenum target, GLenum pname, - GLfloat params ); -GLAPI void GLAPIENTRY glConvolutionParameterfv( GLenum target, GLenum pname, - const GLfloat *params ); +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); -GLAPI void GLAPIENTRY glConvolutionParameteri( GLenum target, GLenum pname, - GLint params ); +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); -GLAPI void GLAPIENTRY glConvolutionParameteriv( GLenum target, GLenum pname, - const GLint *params ); -GLAPI void GLAPIENTRY glCopyConvolutionFilter1D( GLenum target, - GLenum internalformat, GLint x, GLint y, GLsizei width ); +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ -GLAPI void GLAPIENTRY glCopyConvolutionFilter2D( GLenum target, - GLenum internalformat, GLint x, GLint y, GLsizei width, - GLsizei height); +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ -GLAPI void GLAPIENTRY glGetConvolutionFilter( GLenum target, GLenum format, - GLenum type, GLvoid *image ); -GLAPI void GLAPIENTRY glGetConvolutionParameterfv( GLenum target, GLenum pname, - GLfloat *params ); +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); -GLAPI void GLAPIENTRY glGetConvolutionParameteriv( GLenum target, GLenum pname, - GLint *params ); +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); -GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, - GLenum internalformat, GLsizei width, GLsizei height, GLenum format, - GLenum type, const GLvoid *row, const GLvoid *column ); +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); -GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, - GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); /* - * OpenGL 1.3 + * Depth Buffer */ -/* multitexture */ -#define GL_TEXTURE0 0x84C0 -#define GL_TEXTURE1 0x84C1 -#define GL_TEXTURE2 0x84C2 -#define GL_TEXTURE3 0x84C3 -#define GL_TEXTURE4 0x84C4 -#define GL_TEXTURE5 0x84C5 -#define GL_TEXTURE6 0x84C6 -#define GL_TEXTURE7 0x84C7 -#define GL_TEXTURE8 0x84C8 -#define GL_TEXTURE9 0x84C9 -#define GL_TEXTURE10 0x84CA -#define GL_TEXTURE11 0x84CB -#define GL_TEXTURE12 0x84CC -#define GL_TEXTURE13 0x84CD -#define GL_TEXTURE14 0x84CE -#define GL_TEXTURE15 0x84CF -#define GL_TEXTURE16 0x84D0 -#define GL_TEXTURE17 0x84D1 -#define GL_TEXTURE18 0x84D2 -#define GL_TEXTURE19 0x84D3 -#define GL_TEXTURE20 0x84D4 -#define GL_TEXTURE21 0x84D5 -#define GL_TEXTURE22 0x84D6 -#define GL_TEXTURE23 0x84D7 -#define GL_TEXTURE24 0x84D8 -#define GL_TEXTURE25 0x84D9 -#define GL_TEXTURE26 0x84DA -#define GL_TEXTURE27 0x84DB -#define GL_TEXTURE28 0x84DC +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif + + +/* + * OpenGL 1.2 + */ + +#define GL_RESCALE_NORMAL 0x803A +#define GL_CLAMP_TO_EDGE 0x812F +#define GL_MAX_ELEMENTS_VERTICES 0x80E8 +#define GL_MAX_ELEMENTS_INDICES 0x80E9 +#define GL_BGR 0x80E0 +#define GL_BGRA 0x80E1 +#define GL_UNSIGNED_BYTE_3_3_2 0x8032 +#define GL_UNSIGNED_BYTE_2_3_3_REV 0x8362 +#define GL_UNSIGNED_SHORT_5_6_5 0x8363 +#define GL_UNSIGNED_SHORT_5_6_5_REV 0x8364 +#define GL_UNSIGNED_SHORT_4_4_4_4 0x8033 +#define GL_UNSIGNED_SHORT_4_4_4_4_REV 0x8365 +#define GL_UNSIGNED_SHORT_5_5_5_1 0x8034 +#define GL_UNSIGNED_SHORT_1_5_5_5_REV 0x8366 +#define GL_UNSIGNED_INT_8_8_8_8 0x8035 +#define GL_UNSIGNED_INT_8_8_8_8_REV 0x8367 +#define GL_UNSIGNED_INT_10_10_10_2 0x8036 +#define GL_UNSIGNED_INT_2_10_10_10_REV 0x8368 +#define GL_LIGHT_MODEL_COLOR_CONTROL 0x81F8 +#define GL_SINGLE_COLOR 0x81F9 +#define GL_SEPARATE_SPECULAR_COLOR 0x81FA +#define GL_TEXTURE_MIN_LOD 0x813A +#define GL_TEXTURE_MAX_LOD 0x813B +#define GL_TEXTURE_BASE_LEVEL 0x813C +#define GL_TEXTURE_MAX_LEVEL 0x813D +#define GL_SMOOTH_POINT_SIZE_RANGE 0x0B12 +#define GL_SMOOTH_POINT_SIZE_GRANULARITY 0x0B13 +#define GL_SMOOTH_LINE_WIDTH_RANGE 0x0B22 +#define GL_SMOOTH_LINE_WIDTH_GRANULARITY 0x0B23 +#define GL_ALIASED_POINT_SIZE_RANGE 0x846D +#define GL_ALIASED_LINE_WIDTH_RANGE 0x846E +#define GL_PACK_SKIP_IMAGES 0x806B +#define GL_PACK_IMAGE_HEIGHT 0x806C +#define GL_UNPACK_SKIP_IMAGES 0x806D +#define GL_UNPACK_IMAGE_HEIGHT 0x806E +#define GL_TEXTURE_3D 0x806F +#define GL_PROXY_TEXTURE_3D 0x8070 +#define GL_TEXTURE_DEPTH 0x8071 +#define GL_TEXTURE_WRAP_R 0x8072 +#define GL_MAX_3D_TEXTURE_SIZE 0x8073 +#define GL_TEXTURE_BINDING_3D 0x806A + +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + +GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +GLAPI void GLAPIENTRY glTexImage3D( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +GLAPI void GLAPIENTRY glTexSubImage3D( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLint x, GLint y, GLsizei width, GLsizei height); + + +/* + * GL_ARB_imaging + */ + +#define GL_CONSTANT_COLOR 0x8001 +#define GL_ONE_MINUS_CONSTANT_COLOR 0x8002 +#define GL_CONSTANT_ALPHA 0x8003 +#define GL_ONE_MINUS_CONSTANT_ALPHA 0x8004 +#define GL_COLOR_TABLE 0x80D0 +#define GL_POST_CONVOLUTION_COLOR_TABLE 0x80D1 +#define GL_POST_COLOR_MATRIX_COLOR_TABLE 0x80D2 +#define GL_PROXY_COLOR_TABLE 0x80D3 +#define GL_PROXY_POST_CONVOLUTION_COLOR_TABLE 0x80D4 +#define GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE 0x80D5 +#define GL_COLOR_TABLE_SCALE 0x80D6 +#define GL_COLOR_TABLE_BIAS 0x80D7 +#define GL_COLOR_TABLE_FORMAT 0x80D8 +#define GL_COLOR_TABLE_WIDTH 0x80D9 +#define GL_COLOR_TABLE_RED_SIZE 0x80DA +#define GL_COLOR_TABLE_GREEN_SIZE 0x80DB +#define GL_COLOR_TABLE_BLUE_SIZE 0x80DC +#define GL_COLOR_TABLE_ALPHA_SIZE 0x80DD +#define GL_COLOR_TABLE_LUMINANCE_SIZE 0x80DE +#define GL_COLOR_TABLE_INTENSITY_SIZE 0x80DF +#define GL_CONVOLUTION_1D 0x8010 +#define GL_CONVOLUTION_2D 0x8011 +#define GL_SEPARABLE_2D 0x8012 +#define GL_CONVOLUTION_BORDER_MODE 0x8013 +#define GL_CONVOLUTION_FILTER_SCALE 0x8014 +#define GL_CONVOLUTION_FILTER_BIAS 0x8015 +#define GL_REDUCE 0x8016 +#define GL_CONVOLUTION_FORMAT 0x8017 +#define GL_CONVOLUTION_WIDTH 0x8018 +#define GL_CONVOLUTION_HEIGHT 0x8019 +#define GL_MAX_CONVOLUTION_WIDTH 0x801A +#define GL_MAX_CONVOLUTION_HEIGHT 0x801B +#define GL_POST_CONVOLUTION_RED_SCALE 0x801C +#define GL_POST_CONVOLUTION_GREEN_SCALE 0x801D +#define GL_POST_CONVOLUTION_BLUE_SCALE 0x801E +#define GL_POST_CONVOLUTION_ALPHA_SCALE 0x801F +#define GL_POST_CONVOLUTION_RED_BIAS 0x8020 +#define GL_POST_CONVOLUTION_GREEN_BIAS 0x8021 +#define GL_POST_CONVOLUTION_BLUE_BIAS 0x8022 +#define GL_POST_CONVOLUTION_ALPHA_BIAS 0x8023 +#define GL_CONSTANT_BORDER 0x8151 +#define GL_REPLICATE_BORDER 0x8153 +#define GL_CONVOLUTION_BORDER_COLOR 0x8154 +#define GL_COLOR_MATRIX 0x80B1 +#define GL_COLOR_MATRIX_STACK_DEPTH 0x80B2 +#define GL_MAX_COLOR_MATRIX_STACK_DEPTH 0x80B3 +#define GL_POST_COLOR_MATRIX_RED_SCALE 0x80B4 +#define GL_POST_COLOR_MATRIX_GREEN_SCALE 0x80B5 +#define GL_POST_COLOR_MATRIX_BLUE_SCALE 0x80B6 +#define GL_POST_COLOR_MATRIX_ALPHA_SCALE 0x80B7 +#define GL_POST_COLOR_MATRIX_RED_BIAS 0x80B8 +#define GL_POST_COLOR_MATRIX_GREEN_BIAS 0x80B9 +#define GL_POST_COLOR_MATRIX_BLUE_BIAS 0x80BA +#define GL_POST_COLOR_MATRIX_ALPHA_BIAS 0x80BB +#define GL_HISTOGRAM 0x8024 +#define GL_PROXY_HISTOGRAM 0x8025 +#define GL_HISTOGRAM_WIDTH 0x8026 +#define GL_HISTOGRAM_FORMAT 0x8027 +#define GL_HISTOGRAM_RED_SIZE 0x8028 +#define GL_HISTOGRAM_GREEN_SIZE 0x8029 +#define GL_HISTOGRAM_BLUE_SIZE 0x802A +#define GL_HISTOGRAM_ALPHA_SIZE 0x802B +#define GL_HISTOGRAM_LUMINANCE_SIZE 0x802C +#define GL_HISTOGRAM_SINK 0x802D +#define GL_MINMAX 0x802E +#define GL_MINMAX_FORMAT 0x802F +#define GL_MINMAX_SINK 0x8030 +#define GL_TABLE_TOO_LARGE 0x8031 +#define GL_BLEND_EQUATION 0x8009 +#define GL_MIN 0x8007 +#define GL_MAX 0x8008 +#define GL_FUNC_ADD 0x8006 +#define GL_FUNC_SUBTRACT 0x800A +#define GL_FUNC_REVERSE_SUBTRACT 0x800B +#define GL_BLEND_COLOR 0x8005 + + +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + +GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +GLAPI void GLAPIENTRY glColorSubTable( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +GLAPI void GLAPIENTRY glColorTableParameteriv(GLenum target, GLenum pname, + const GLint *params); + +GLAPI void GLAPIENTRY glColorTableParameterfv(GLenum target, GLenum pname, + const GLfloat *params); + +GLAPI void GLAPIENTRY glCopyColorSubTable( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +GLAPI void GLAPIENTRY glCopyColorTable( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +GLAPI void GLAPIENTRY glGetColorTable( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +GLAPI void GLAPIENTRY glGetColorTableParameterfv( GLenum target, GLenum pname, + GLfloat *params ); + +GLAPI void GLAPIENTRY glGetColorTableParameteriv( GLenum target, GLenum pname, + GLint *params ); + +GLAPI void GLAPIENTRY glBlendEquation( GLenum mode ); + +GLAPI void GLAPIENTRY glBlendColor( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +GLAPI void GLAPIENTRY glHistogram( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +GLAPI void GLAPIENTRY glResetHistogram( GLenum target ); + +GLAPI void GLAPIENTRY glGetHistogram( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +GLAPI void GLAPIENTRY glGetHistogramParameterfv( GLenum target, GLenum pname, + GLfloat *params ); + +GLAPI void GLAPIENTRY glGetHistogramParameteriv( GLenum target, GLenum pname, + GLint *params ); + +GLAPI void GLAPIENTRY glMinmax( GLenum target, GLenum internalformat, + GLboolean sink ); + +GLAPI void GLAPIENTRY glResetMinmax( GLenum target ); + +GLAPI void GLAPIENTRY glGetMinmax( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +GLAPI void GLAPIENTRY glGetMinmaxParameterfv( GLenum target, GLenum pname, + GLfloat *params ); + +GLAPI void GLAPIENTRY glGetMinmaxParameteriv( GLenum target, GLenum pname, + GLint *params ); + +GLAPI void GLAPIENTRY glConvolutionFilter1D( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +GLAPI void GLAPIENTRY glConvolutionFilter2D( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +GLAPI void GLAPIENTRY glConvolutionParameterf( GLenum target, GLenum pname, + GLfloat params ); + +GLAPI void GLAPIENTRY glConvolutionParameterfv( GLenum target, GLenum pname, + const GLfloat *params ); + +GLAPI void GLAPIENTRY glConvolutionParameteri( GLenum target, GLenum pname, + GLint params ); + +GLAPI void GLAPIENTRY glConvolutionParameteriv( GLenum target, GLenum pname, + const GLint *params ); + +GLAPI void GLAPIENTRY glCopyConvolutionFilter1D( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +GLAPI void GLAPIENTRY glCopyConvolutionFilter2D( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +GLAPI void GLAPIENTRY glGetConvolutionFilter( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +GLAPI void GLAPIENTRY glGetConvolutionParameterfv( GLenum target, GLenum pname, + GLfloat *params ); + +GLAPI void GLAPIENTRY glGetConvolutionParameteriv( GLenum target, GLenum pname, + GLint *params ); + +GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + + + + +/* + * OpenGL 1.3 + */ + +/* multitexture */ +#define GL_TEXTURE0 0x84C0 +#define GL_TEXTURE1 0x84C1 +#define GL_TEXTURE2 0x84C2 +#define GL_TEXTURE3 0x84C3 +#define GL_TEXTURE4 0x84C4 +#define GL_TEXTURE5 0x84C5 +#define GL_TEXTURE6 0x84C6 +#define GL_TEXTURE7 0x84C7 +#define GL_TEXTURE8 0x84C8 +#define GL_TEXTURE9 0x84C9 +#define GL_TEXTURE10 0x84CA +#define GL_TEXTURE11 0x84CB +#define GL_TEXTURE12 0x84CC +#define GL_TEXTURE13 0x84CD +#define GL_TEXTURE14 0x84CE +#define GL_TEXTURE15 0x84CF +#define GL_TEXTURE16 0x84D0 +#define GL_TEXTURE17 0x84D1 +#define GL_TEXTURE18 0x84D2 +#define GL_TEXTURE19 0x84D3 +#define GL_TEXTURE20 0x84D4 +#define GL_TEXTURE21 0x84D5 +#define GL_TEXTURE22 0x84D6 +#define GL_TEXTURE23 0x84D7 +#define GL_TEXTURE24 0x84D8 +#define GL_TEXTURE25 0x84D9 +#define GL_TEXTURE26 0x84DA +#define GL_TEXTURE27 0x84DB +#define GL_TEXTURE28 0x84DC #define GL_TEXTURE29 0x84DD #define GL_TEXTURE30 0x84DE #define GL_TEXTURE31 0x84DF @@ -1869,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1962,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2017,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2052,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); @@ -2096,7 +3073,7 @@ typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLsh * defined in gl.h). Otherwise, extensions will be included from glext.h. */ #if !defined(NO_SDL_GLEXT) && !defined(GL_GLEXT_LEGACY) -#include "SDL_opengl_glext.h" +#include #endif /* GL_GLEXT_LEGACY */ @@ -2119,8 +3096,6 @@ typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLsh #endif /* __gl_h_ */ -#endif /* !__IPHONEOS__ */ +#endif /* !SDL_PLATFORM_IOS */ #endif /* SDL_opengl_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengl_glext.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl_glext.h similarity index 99% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengl_glext.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl_glext.h index ff6ad12cef..fa0f6c2a5b 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_opengl_glext.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengl_glext.h @@ -9807,15 +9807,15 @@ typedef void (APIENTRYP PFNGLUPLOADGPUMASKNVXPROC) (GLbitfield mask); typedef void (APIENTRYP PFNGLMULTICASTVIEWPORTARRAYVNVXPROC) (GLuint gpu, GLuint first, GLsizei count, const GLfloat *v); typedef void (APIENTRYP PFNGLMULTICASTVIEWPORTPOSITIONWSCALENVXPROC) (GLuint gpu, GLuint index, GLfloat xcoeff, GLfloat ycoeff); typedef void (APIENTRYP PFNGLMULTICASTSCISSORARRAYVNVXPROC) (GLuint gpu, GLuint first, GLsizei count, const GLint *v); -typedef GLuint (APIENTRYP PFNGLASYNCCOPYBUFFERSUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); -typedef GLuint (APIENTRYP PFNGLASYNCCOPYIMAGESUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +typedef GLuint (APIENTRYP PFNGLASYNCCOPYBUFFERSUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +typedef GLuint (APIENTRYP PFNGLASYNCCOPYIMAGESUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); #ifdef GL_GLEXT_PROTOTYPES -GLAPI void APIENTRY glUploadGpuMaskNVX (GLbitfield mask); +GLAPI void APIENTRY glUploadGPUMaskNVX (GLbitfield mask); GLAPI void APIENTRY glMulticastViewportArrayvNVX (GLuint gpu, GLuint first, GLsizei count, const GLfloat *v); GLAPI void APIENTRY glMulticastViewportPositionWScaleNVX (GLuint gpu, GLuint index, GLfloat xcoeff, GLfloat ycoeff); GLAPI void APIENTRY glMulticastScissorArrayvNVX (GLuint gpu, GLuint first, GLsizei count, const GLint *v); -GLAPI GLuint APIENTRY glAsyncCopyBufferSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); -GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +GLAPI GLuint APIENTRY glAsyncCopyBufferSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); #endif #endif /* GL_NVX_gpu_multicast2 */ @@ -9824,11 +9824,11 @@ GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, co #define GL_LGPU_SEPARATE_STORAGE_BIT_NVX 0x0800 #define GL_MAX_LGPU_GPUS_NVX 0x92BA typedef void (APIENTRYP PFNGLLGPUNAMEDBUFFERSUBDATANVXPROC) (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -typedef void (APIENTRYP PFNGLLGPUCOPYIMAGESUBDATANVXPROC) (GLuint sourceGpu, GLbitfield destinationGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); +typedef void (APIENTRYP PFNGLLGPUCOPYIMAGESUBDATANVXPROC) (GLuint sourceGPU, GLbitfield destinationGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); typedef void (APIENTRYP PFNGLLGPUINTERLOCKNVXPROC) (void); #ifdef GL_GLEXT_PROTOTYPES GLAPI void APIENTRY glLGPUNamedBufferSubDataNVX (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -GLAPI void APIENTRY glLGPUCopyImageSubDataNVX (GLuint sourceGpu, GLbitfield destinationGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); +GLAPI void APIENTRY glLGPUCopyImageSubDataNVX (GLuint sourceGPU, GLbitfield destinationGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); GLAPI void APIENTRY glLGPUInterlockNVX (void); #endif #endif /* GL_NVX_linked_gpu_multicast */ @@ -9836,13 +9836,13 @@ GLAPI void APIENTRY glLGPUInterlockNVX (void); #ifndef GL_NVX_progress_fence #define GL_NVX_progress_fence 1 typedef GLuint (APIENTRYP PFNGLCREATEPROGRESSFENCENVXPROC) (void); -typedef void (APIENTRYP PFNGLSIGNALSEMAPHOREUI64NVXPROC) (GLuint signalGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); -typedef void (APIENTRYP PFNGLWAITSEMAPHOREUI64NVXPROC) (GLuint waitGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +typedef void (APIENTRYP PFNGLSIGNALSEMAPHOREUI64NVXPROC) (GLuint signalGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +typedef void (APIENTRYP PFNGLWAITSEMAPHOREUI64NVXPROC) (GLuint waitGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); typedef void (APIENTRYP PFNGLCLIENTWAITSEMAPHOREUI64NVXPROC) (GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); #ifdef GL_GLEXT_PROTOTYPES GLAPI GLuint APIENTRY glCreateProgressFenceNVX (void); -GLAPI void APIENTRY glSignalSemaphoreui64NVX (GLuint signalGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); -GLAPI void APIENTRY glWaitSemaphoreui64NVX (GLuint waitGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +GLAPI void APIENTRY glSignalSemaphoreui64NVX (GLuint signalGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +GLAPI void APIENTRY glWaitSemaphoreui64NVX (GLuint waitGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); GLAPI void APIENTRY glClientWaitSemaphoreui64NVX (GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); #endif #endif /* GL_NVX_progress_fence */ @@ -10433,25 +10433,25 @@ GLAPI void APIENTRY glFramebufferTextureFaceEXT (GLenum target, GLenum attachmen #define GL_MULTICAST_PROGRAMMABLE_SAMPLE_LOCATION_NV 0x9549 typedef void (APIENTRYP PFNGLRENDERGPUMASKNVPROC) (GLbitfield mask); typedef void (APIENTRYP PFNGLMULTICASTBUFFERSUBDATANVPROC) (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -typedef void (APIENTRYP PFNGLMULTICASTCOPYBUFFERSUBDATANVPROC) (GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); -typedef void (APIENTRYP PFNGLMULTICASTCOPYIMAGESUBDATANVPROC) (GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); -typedef void (APIENTRYP PFNGLMULTICASTBLITFRAMEBUFFERNVPROC) (GLuint srcGpu, GLuint dstGpu, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); +typedef void (APIENTRYP PFNGLMULTICASTCOPYBUFFERSUBDATANVPROC) (GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); +typedef void (APIENTRYP PFNGLMULTICASTCOPYIMAGESUBDATANVPROC) (GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); +typedef void (APIENTRYP PFNGLMULTICASTBLITFRAMEBUFFERNVPROC) (GLuint srcGPU, GLuint dstGPU, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); typedef void (APIENTRYP PFNGLMULTICASTFRAMEBUFFERSAMPLELOCATIONSFVNVPROC) (GLuint gpu, GLuint framebuffer, GLuint start, GLsizei count, const GLfloat *v); typedef void (APIENTRYP PFNGLMULTICASTBARRIERNVPROC) (void); -typedef void (APIENTRYP PFNGLMULTICASTWAITSYNCNVPROC) (GLuint signalGpu, GLbitfield waitGpuMask); +typedef void (APIENTRYP PFNGLMULTICASTWAITSYNCNVPROC) (GLuint signalGPU, GLbitfield waitGPUMask); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTIVNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLint *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTUIVNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLuint *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTI64VNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLint64 *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTUI64VNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLuint64 *params); #ifdef GL_GLEXT_PROTOTYPES -GLAPI void APIENTRY glRenderGpuMaskNV (GLbitfield mask); +GLAPI void APIENTRY glRenderGPUMaskNV (GLbitfield mask); GLAPI void APIENTRY glMulticastBufferSubDataNV (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -GLAPI void APIENTRY glMulticastCopyBufferSubDataNV (GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); -GLAPI void APIENTRY glMulticastCopyImageSubDataNV (GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); -GLAPI void APIENTRY glMulticastBlitFramebufferNV (GLuint srcGpu, GLuint dstGpu, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); +GLAPI void APIENTRY glMulticastCopyBufferSubDataNV (GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); +GLAPI void APIENTRY glMulticastCopyImageSubDataNV (GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); +GLAPI void APIENTRY glMulticastBlitFramebufferNV (GLuint srcGPU, GLuint dstGPU, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); GLAPI void APIENTRY glMulticastFramebufferSampleLocationsfvNV (GLuint gpu, GLuint framebuffer, GLuint start, GLsizei count, const GLfloat *v); GLAPI void APIENTRY glMulticastBarrierNV (void); -GLAPI void APIENTRY glMulticastWaitSyncNV (GLuint signalGpu, GLbitfield waitGpuMask); +GLAPI void APIENTRY glMulticastWaitSyncNV (GLuint signalGPU, GLbitfield waitGPUMask); GLAPI void APIENTRY glMulticastGetQueryObjectivNV (GLuint gpu, GLuint id, GLenum pname, GLint *params); GLAPI void APIENTRY glMulticastGetQueryObjectuivNV (GLuint gpu, GLuint id, GLenum pname, GLuint *params); GLAPI void APIENTRY glMulticastGetQueryObjecti64vNV (GLuint gpu, GLuint id, GLenum pname, GLint64 *params); diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles.h similarity index 94% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles.h index adf6ef782f..4fb9a4b702 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles.h @@ -23,9 +23,9 @@ * This is a simple file to encapsulate the OpenGL ES 1.X API headers. */ -#include "SDL_config.h" +#include -#ifdef __IPHONEOS__ +#ifdef SDL_PLATFORM_IOS #include #include #else diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2.h similarity index 86% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles2.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2.h index 5514197124..365898a65b 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2.h @@ -23,11 +23,11 @@ * This is a simple file to encapsulate the OpenGL ES 2.0 API headers. */ -#include "SDL_config.h" +#include #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) -#ifdef __IPHONEOS__ +#ifdef SDL_PLATFORM_IOS #include #include #else @@ -39,10 +39,10 @@ #else /* _MSC_VER */ /* OpenGL ES2 headers for Visual Studio */ -#include "SDL_opengles2_khrplatform.h" -#include "SDL_opengles2_gl2platform.h" -#include "SDL_opengles2_gl2.h" -#include "SDL_opengles2_gl2ext.h" +#include +#include +#include +#include #endif /* _MSC_VER */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2.h similarity index 100% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2.h diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2ext.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2ext.h similarity index 100% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2ext.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2ext.h diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2platform.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2platform.h similarity index 100% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_gl2platform.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_gl2platform.h diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_khrplatform.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_khrplatform.h similarity index 100% rename from code/thirdparty/SDL2-2.32.8/include/SDL_opengles2_khrplatform.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_opengles2_khrplatform.h diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pen.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pen.h new file mode 100644 index 0000000000..5182eeb0ce --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pen.h @@ -0,0 +1,127 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryPen + * + * SDL pen event handling. + * + * SDL provides an API for pressure-sensitive pen (stylus and/or eraser) + * handling, e.g., for input and drawing tablets or suitably equipped mobile / + * tablet devices. + * + * To get started with pens, simply handle SDL_EVENT_PEN_* events. When a pen + * starts providing input, SDL will assign it a unique SDL_PenID, which will + * remain for the life of the process, as long as the pen stays connected. + * + * Pens may provide more than simple touch input; they might have other axes, + * such as pressure, tilt, rotation, etc. + */ + +#ifndef SDL_pen_h_ +#define SDL_pen_h_ + +#include +#include +#include + +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * SDL pen instance IDs. + * + * Zero is used to signify an invalid/null device. + * + * These show up in pen events when SDL sees input from them. They remain + * consistent as long as SDL can recognize a tool to be the same pen; but if a + * pen physically leaves the area and returns, it might get a new ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_PenID; + +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + + +/** + * Pen input flags, as reported by various pen events' `pen_state` field. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_PenInputFlags; + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ + +/** + * Pen axis indices. + * + * These are the valid values for the `axis` field in SDL_PenAxisEvent. All + * axes are either normalised to 0..1 or report a (positive or negative) angle + * in degrees, with 0.0 representing the centre. Not all pens/backends support + * all axes: unsupported axes are always zero. + * + * To convert angles for tilt and rotation into vector representation, use + * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example: + * + * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PenAxis +{ + SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ + SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ + SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ + SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ + SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ +} SDL_PenAxis; + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif + +#endif /* SDL_pen_h_ */ + diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pixels.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pixels.h new file mode 100644 index 0000000000..39596c1c98 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_pixels.h @@ -0,0 +1,1441 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryPixels + * + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. + */ + +#ifndef SDL_pixels_h_ +#define SDL_pixels_h_ + +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * A fully opaque 8-bit alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT + */ +#define SDL_ALPHA_OPAQUE 255 + +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + +/** + * A fully transparent 8-bit alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE + */ +#define SDL_ALPHA_TRANSPARENT 0 + +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PixelType +{ + SDL_PIXELTYPE_UNKNOWN, + SDL_PIXELTYPE_INDEX1, + SDL_PIXELTYPE_INDEX4, + SDL_PIXELTYPE_INDEX8, + SDL_PIXELTYPE_PACKED8, + SDL_PIXELTYPE_PACKED16, + SDL_PIXELTYPE_PACKED32, + SDL_PIXELTYPE_ARRAYU8, + SDL_PIXELTYPE_ARRAYU16, + SDL_PIXELTYPE_ARRAYU32, + SDL_PIXELTYPE_ARRAYF16, + SDL_PIXELTYPE_ARRAYF32, + /* appended at the end for compatibility with sdl2-compat: */ + SDL_PIXELTYPE_INDEX2 +} SDL_PixelType; + +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_BitmapOrder +{ + SDL_BITMAPORDER_NONE, + SDL_BITMAPORDER_4321, + SDL_BITMAPORDER_1234 +} SDL_BitmapOrder; + +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PackedOrder +{ + SDL_PACKEDORDER_NONE, + SDL_PACKEDORDER_XRGB, + SDL_PACKEDORDER_RGBX, + SDL_PACKEDORDER_ARGB, + SDL_PACKEDORDER_RGBA, + SDL_PACKEDORDER_XBGR, + SDL_PACKEDORDER_BGRX, + SDL_PACKEDORDER_ABGR, + SDL_PACKEDORDER_BGRA +} SDL_PackedOrder; + +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ArrayOrder +{ + SDL_ARRAYORDER_NONE, + SDL_ARRAYORDER_RGB, + SDL_ARRAYORDER_RGBA, + SDL_ARRAYORDER_ARGB, + SDL_ARRAYORDER_BGR, + SDL_ARRAYORDER_BGRA, + SDL_ARRAYORDER_ABGR +} SDL_ArrayOrder; + +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PackedLayout +{ + SDL_PACKEDLAYOUT_NONE, + SDL_PACKEDLAYOUT_332, + SDL_PACKEDLAYOUT_4444, + SDL_PACKEDLAYOUT_1555, + SDL_PACKEDLAYOUT_5551, + SDL_PACKEDLAYOUT_565, + SDL_PACKEDLAYOUT_8888, + SDL_PACKEDLAYOUT_2101010, + 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.2.0. + */ +#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.2.0. + */ +#define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ + ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ + ((bits) << 8) | ((bytes) << 0)) + +/** + * 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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + * + * \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.2.0. + * + * \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.2.0. + */ +#define SDL_ISPIXELFORMAT_INDEXED(format) \ + (!SDL_ISPIXELFORMAT_FOURCC(format) && \ + ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ + (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \ + (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.2.0. + */ +#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.2.0. + */ +#define SDL_ISPIXELFORMAT_ARRAY(format) \ + (!SDL_ISPIXELFORMAT_FOURCC(format) && \ + ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ + (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU16) || \ + (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU32) || \ + (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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * 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.2.0. + */ +#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() */ + +/** + * Pixel format. + * + * SDL's pixel formats have the following naming convention: + * + * - Names with a list of components and a single bit count, such as RGB24 and + * ABGR32, define a platform-independent encoding into bytes in the order + * specified. For example, in RGB24 data, each pixel is encoded in 3 bytes + * (red, green, blue) in that order, and in ABGR32 data, each pixel is + * encoded in 4 bytes (alpha, blue, green, red) in that order. Use these + * names if the property of a format that is important to you is the order + * of the bytes in memory or on disk. + * - Names with a bit count per component, such as ARGB8888 and XRGB1555, are + * "packed" into an appropriately-sized integer in the platform's native + * endianness. For example, ARGB8888 is a sequence of 32-bit integers; in + * each integer, the most significant bits are alpha, and the least + * significant bits are blue. On a little-endian CPU such as x86, the least + * significant bits of each integer are arranged first in memory, but on a + * big-endian CPU such as s390x, the most significant bits are arranged + * first. Use these names if the property of a format that is important to + * you is the meaning of each bit position within a native-endianness + * integer. + * - In indexed formats such as INDEX4LSB, each pixel is represented by + * encoding an index into the palette into the indicated number of bits, + * with multiple pixels packed into each byte if appropriate. In LSB + * formats, the first (leftmost) pixel is stored in the least-significant + * bits of the byte; in MSB formats, it's stored in the most-significant + * bits. INDEX8 does not need LSB/MSB variants, because each pixel exactly + * fills one byte. + * + * The 32-bit byte-array encodings such as RGBA32 are aliases for the + * appropriate 8888 encoding for the current platform. For example, RGBA32 is + * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for + * RGBA8888 on big-endian CPUs. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PixelFormat +{ + SDL_PIXELFORMAT_UNKNOWN = 0, + SDL_PIXELFORMAT_INDEX1LSB = 0x11100100u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, 1, 0), */ + SDL_PIXELFORMAT_INDEX1MSB = 0x11200100u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, 1, 0), */ + SDL_PIXELFORMAT_INDEX2LSB = 0x1c100200u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, 2, 0), */ + SDL_PIXELFORMAT_INDEX2MSB = 0x1c200200u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, 2, 0), */ + SDL_PIXELFORMAT_INDEX4LSB = 0x12100400u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, 4, 0), */ + SDL_PIXELFORMAT_INDEX4MSB = 0x12200400u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, 4, 0), */ + SDL_PIXELFORMAT_INDEX8 = 0x13000801u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), */ + SDL_PIXELFORMAT_RGB332 = 0x14110801u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_332, 8, 1), */ + SDL_PIXELFORMAT_XRGB4444 = 0x15120c02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_4444, 12, 2), */ + SDL_PIXELFORMAT_XBGR4444 = 0x15520c02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_4444, 12, 2), */ + SDL_PIXELFORMAT_XRGB1555 = 0x15130f02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_1555, 15, 2), */ + SDL_PIXELFORMAT_XBGR1555 = 0x15530f02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_1555, 15, 2), */ + SDL_PIXELFORMAT_ARGB4444 = 0x15321002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_4444, 16, 2), */ + SDL_PIXELFORMAT_RGBA4444 = 0x15421002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_4444, 16, 2), */ + SDL_PIXELFORMAT_ABGR4444 = 0x15721002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_4444, 16, 2), */ + SDL_PIXELFORMAT_BGRA4444 = 0x15821002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_4444, 16, 2), */ + SDL_PIXELFORMAT_ARGB1555 = 0x15331002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_1555, 16, 2), */ + SDL_PIXELFORMAT_RGBA5551 = 0x15441002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_5551, 16, 2), */ + SDL_PIXELFORMAT_ABGR1555 = 0x15731002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_1555, 16, 2), */ + SDL_PIXELFORMAT_BGRA5551 = 0x15841002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_5551, 16, 2), */ + SDL_PIXELFORMAT_RGB565 = 0x15151002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_565, 16, 2), */ + SDL_PIXELFORMAT_BGR565 = 0x15551002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_565, 16, 2), */ + SDL_PIXELFORMAT_RGB24 = 0x17101803u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, 24, 3), */ + SDL_PIXELFORMAT_BGR24 = 0x17401803u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, 24, 3), */ + SDL_PIXELFORMAT_XRGB8888 = 0x16161804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_8888, 24, 4), */ + SDL_PIXELFORMAT_RGBX8888 = 0x16261804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, SDL_PACKEDLAYOUT_8888, 24, 4), */ + SDL_PIXELFORMAT_XBGR8888 = 0x16561804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_8888, 24, 4), */ + SDL_PIXELFORMAT_BGRX8888 = 0x16661804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, SDL_PACKEDLAYOUT_8888, 24, 4), */ + SDL_PIXELFORMAT_ARGB8888 = 0x16362004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_8888, 32, 4), */ + SDL_PIXELFORMAT_RGBA8888 = 0x16462004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4), */ + SDL_PIXELFORMAT_ABGR8888 = 0x16762004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_8888, 32, 4), */ + SDL_PIXELFORMAT_BGRA8888 = 0x16862004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_8888, 32, 4), */ + SDL_PIXELFORMAT_XRGB2101010 = 0x16172004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + SDL_PIXELFORMAT_XBGR2101010 = 0x16572004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + SDL_PIXELFORMAT_ARGB2101010 = 0x16372004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + SDL_PIXELFORMAT_ABGR2101010 = 0x16772004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + SDL_PIXELFORMAT_RGB48 = 0x18103006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ + SDL_PIXELFORMAT_BGR48 = 0x18403006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ + SDL_PIXELFORMAT_RGBA64 = 0x18204008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ + SDL_PIXELFORMAT_ARGB64 = 0x18304008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ + SDL_PIXELFORMAT_BGRA64 = 0x18504008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ + SDL_PIXELFORMAT_ABGR64 = 0x18604008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ + SDL_PIXELFORMAT_RGB48_FLOAT = 0x1a103006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ + SDL_PIXELFORMAT_BGR48_FLOAT = 0x1a403006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ + SDL_PIXELFORMAT_RGBA64_FLOAT = 0x1a204008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ + SDL_PIXELFORMAT_ARGB64_FLOAT = 0x1a304008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ + SDL_PIXELFORMAT_BGRA64_FLOAT = 0x1a504008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ + SDL_PIXELFORMAT_ABGR64_FLOAT = 0x1a604008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ + SDL_PIXELFORMAT_RGB96_FLOAT = 0x1b10600cu, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGB, 0, 96, 12), */ + SDL_PIXELFORMAT_BGR96_FLOAT = 0x1b40600cu, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGR, 0, 96, 12), */ + SDL_PIXELFORMAT_RGBA128_FLOAT = 0x1b208010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGBA, 0, 128, 16), */ + SDL_PIXELFORMAT_ARGB128_FLOAT = 0x1b308010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ARGB, 0, 128, 16), */ + SDL_PIXELFORMAT_BGRA128_FLOAT = 0x1b508010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGRA, 0, 128, 16), */ + SDL_PIXELFORMAT_ABGR128_FLOAT = 0x1b608010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ABGR, 0, 128, 16), */ + + SDL_PIXELFORMAT_YV12 = 0x32315659u, /**< Planar mode: Y + V + U (3 planes) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), */ + SDL_PIXELFORMAT_IYUV = 0x56555949u, /**< Planar mode: Y + U + V (3 planes) */ + /* SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), */ + SDL_PIXELFORMAT_YUY2 = 0x32595559u, /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), */ + SDL_PIXELFORMAT_UYVY = 0x59565955u, /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), */ + SDL_PIXELFORMAT_YVYU = 0x55595659u, /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), */ + SDL_PIXELFORMAT_NV12 = 0x3231564eu, /**< Planar mode: Y + U/V interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), */ + SDL_PIXELFORMAT_NV21 = 0x3132564eu, /**< Planar mode: Y + V/U interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ + SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ + /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + SDL_PIXELFORMAT_MJPG = 0x47504a4du, /**< Motion JPEG */ + /* SDL_DEFINE_PIXELFOURCC('M', 'J', 'P', 'G') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif +} SDL_PixelFormat; + +/** + * Colorspace color type. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ColorType +{ + SDL_COLOR_TYPE_UNKNOWN = 0, + SDL_COLOR_TYPE_RGB = 1, + SDL_COLOR_TYPE_YCBCR = 2 +} SDL_ColorType; + +/** + * Colorspace color range, as described by + * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ColorRange +{ + SDL_COLOR_RANGE_UNKNOWN = 0, + SDL_COLOR_RANGE_LIMITED = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */ + SDL_COLOR_RANGE_FULL = 2 /**< Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma */ +} SDL_ColorRange; + +/** + * Colorspace color primaries, as described by + * https://www.itu.int/rec/T-REC-H.273-201612-S/en + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ColorPrimaries +{ + SDL_COLOR_PRIMARIES_UNKNOWN = 0, + SDL_COLOR_PRIMARIES_BT709 = 1, /**< ITU-R BT.709-6 */ + SDL_COLOR_PRIMARIES_UNSPECIFIED = 2, + SDL_COLOR_PRIMARIES_BT470M = 4, /**< ITU-R BT.470-6 System M */ + SDL_COLOR_PRIMARIES_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625 */ + SDL_COLOR_PRIMARIES_BT601 = 6, /**< ITU-R BT.601-7 525, SMPTE 170M */ + SDL_COLOR_PRIMARIES_SMPTE240 = 7, /**< SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601 */ + SDL_COLOR_PRIMARIES_GENERIC_FILM = 8, /**< Generic film (color filters using Illuminant C) */ + SDL_COLOR_PRIMARIES_BT2020 = 9, /**< ITU-R BT.2020-2 / ITU-R BT.2100-0 */ + SDL_COLOR_PRIMARIES_XYZ = 10, /**< SMPTE ST 428-1 */ + SDL_COLOR_PRIMARIES_SMPTE431 = 11, /**< SMPTE RP 431-2 */ + SDL_COLOR_PRIMARIES_SMPTE432 = 12, /**< SMPTE EG 432-1 / DCI P3 */ + SDL_COLOR_PRIMARIES_EBU3213 = 22, /**< EBU Tech. 3213-E */ + SDL_COLOR_PRIMARIES_CUSTOM = 31 +} SDL_ColorPrimaries; + +/** + * Colorspace transfer characteristics. + * + * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_TransferCharacteristics +{ + SDL_TRANSFER_CHARACTERISTICS_UNKNOWN = 0, + SDL_TRANSFER_CHARACTERISTICS_BT709 = 1, /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */ + SDL_TRANSFER_CHARACTERISTICS_UNSPECIFIED = 2, + SDL_TRANSFER_CHARACTERISTICS_GAMMA22 = 4, /**< ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM */ + SDL_TRANSFER_CHARACTERISTICS_GAMMA28 = 5, /**< ITU-R BT.470-6 System B, G */ + SDL_TRANSFER_CHARACTERISTICS_BT601 = 6, /**< SMPTE ST 170M / ITU-R BT.601-7 525 or 625 */ + SDL_TRANSFER_CHARACTERISTICS_SMPTE240 = 7, /**< SMPTE ST 240M */ + SDL_TRANSFER_CHARACTERISTICS_LINEAR = 8, + SDL_TRANSFER_CHARACTERISTICS_LOG100 = 9, + SDL_TRANSFER_CHARACTERISTICS_LOG100_SQRT10 = 10, + SDL_TRANSFER_CHARACTERISTICS_IEC61966 = 11, /**< IEC 61966-2-4 */ + SDL_TRANSFER_CHARACTERISTICS_BT1361 = 12, /**< ITU-R BT1361 Extended Colour Gamut */ + SDL_TRANSFER_CHARACTERISTICS_SRGB = 13, /**< IEC 61966-2-1 (sRGB or sYCC) */ + SDL_TRANSFER_CHARACTERISTICS_BT2020_10BIT = 14, /**< ITU-R BT2020 for 10-bit system */ + SDL_TRANSFER_CHARACTERISTICS_BT2020_12BIT = 15, /**< ITU-R BT2020 for 12-bit system */ + SDL_TRANSFER_CHARACTERISTICS_PQ = 16, /**< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems */ + SDL_TRANSFER_CHARACTERISTICS_SMPTE428 = 17, /**< SMPTE ST 428-1 */ + SDL_TRANSFER_CHARACTERISTICS_HLG = 18, /**< ARIB STD-B67, known as "hybrid log-gamma" (HLG) */ + SDL_TRANSFER_CHARACTERISTICS_CUSTOM = 31 +} SDL_TransferCharacteristics; + +/** + * Colorspace matrix coefficients. + * + * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_MatrixCoefficients +{ + SDL_MATRIX_COEFFICIENTS_IDENTITY = 0, + SDL_MATRIX_COEFFICIENTS_BT709 = 1, /**< ITU-R BT.709-6 */ + SDL_MATRIX_COEFFICIENTS_UNSPECIFIED = 2, + SDL_MATRIX_COEFFICIENTS_FCC = 4, /**< US FCC Title 47 */ + SDL_MATRIX_COEFFICIENTS_BT470BG = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625, functionally the same as SDL_MATRIX_COEFFICIENTS_BT601 */ + SDL_MATRIX_COEFFICIENTS_BT601 = 6, /**< ITU-R BT.601-7 525 */ + SDL_MATRIX_COEFFICIENTS_SMPTE240 = 7, /**< SMPTE 240M */ + SDL_MATRIX_COEFFICIENTS_YCGCO = 8, + SDL_MATRIX_COEFFICIENTS_BT2020_NCL = 9, /**< ITU-R BT.2020-2 non-constant luminance */ + SDL_MATRIX_COEFFICIENTS_BT2020_CL = 10, /**< ITU-R BT.2020-2 constant luminance */ + SDL_MATRIX_COEFFICIENTS_SMPTE2085 = 11, /**< SMPTE ST 2085 */ + SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_NCL = 12, + SDL_MATRIX_COEFFICIENTS_CHROMA_DERIVED_CL = 13, + SDL_MATRIX_COEFFICIENTS_ICTCP = 14, /**< ITU-R BT.2100-0 ICTCP */ + SDL_MATRIX_COEFFICIENTS_CUSTOM = 31 +} SDL_MatrixCoefficients; + +/** + * Colorspace chroma sample location. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ChromaLocation +{ + SDL_CHROMA_LOCATION_NONE = 0, /**< RGB, no chroma sampling */ + SDL_CHROMA_LOCATION_LEFT = 1, /**< In MPEG-2, MPEG-4, and AVC, Cb and Cr are taken on midpoint of the left-edge of the 2x2 square. In other words, they have the same horizontal location as the top-left pixel, but is shifted one-half pixel down vertically. */ + SDL_CHROMA_LOCATION_CENTER = 2, /**< In JPEG/JFIF, H.261, and MPEG-1, Cb and Cr are taken at the center of the 2x2 square. In other words, they are offset one-half pixel to the right and one-half pixel down compared to the top-left pixel. */ + SDL_CHROMA_LOCATION_TOPLEFT = 3 /**< In HEVC for BT.2020 and BT.2100 content (in particular on Blu-rays), Cb and Cr are sampled at the same location as the group's top-left Y pixel ("co-sited", "co-located"). */ +} 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.2.0. + */ +#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)) + +/** + * 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.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) + +/** + * 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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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 BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) + +/** + * Colorspace definitions. + * + * Since similar colorspaces may vary in their details (matrix, transfer + * function, etc.), this is not an exhaustive list, but rather a + * representative sample of the kinds of colorspaces supported in SDL. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ColorPrimaries + * \sa SDL_ColorRange + * \sa SDL_ColorType + * \sa SDL_MatrixCoefficients + * \sa SDL_TransferCharacteristics + */ +typedef enum SDL_Colorspace +{ + SDL_COLORSPACE_UNKNOWN = 0, + + /* sRGB is a gamma corrected colorspace, and the default colorspace for SDL rendering and 8-bit RGB surfaces */ + SDL_COLORSPACE_SRGB = 0x120005a0u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709 */ + /* 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), */ + + /* This is a linear colorspace and the default colorspace for floating point surfaces. On Windows this is the scRGB colorspace, and on Apple platforms this is kCGColorSpaceExtendedLinearSRGB for EDR content */ + SDL_COLORSPACE_SRGB_LINEAR = 0x12000500u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT709, + SDL_TRANSFER_CHARACTERISTICS_LINEAR, + SDL_MATRIX_COEFFICIENTS_IDENTITY, + SDL_CHROMA_LOCATION_NONE), */ + + /* HDR10 is a non-linear HDR colorspace and the default colorspace for 10-bit surfaces */ + SDL_COLORSPACE_HDR10 = 0x12002600u, /**< Equivalent to DXGI_COLOR_SPACE_RGB_FULL_G2084_NONE_P2020 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT2020, + SDL_TRANSFER_CHARACTERISTICS_PQ, + SDL_MATRIX_COEFFICIENTS_IDENTITY, + SDL_CHROMA_LOCATION_NONE), */ + + SDL_COLORSPACE_JPEG = 0x220004c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_NONE_P709_X601 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT709, + SDL_TRANSFER_CHARACTERISTICS_BT601, + SDL_MATRIX_COEFFICIENTS_BT601, + SDL_CHROMA_LOCATION_NONE), */ + + SDL_COLORSPACE_BT601_LIMITED = 0x211018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_LIMITED, + SDL_COLOR_PRIMARIES_BT601, + SDL_TRANSFER_CHARACTERISTICS_BT601, + SDL_MATRIX_COEFFICIENTS_BT601, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_BT601_FULL = 0x221018c6u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P601 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT601, + SDL_TRANSFER_CHARACTERISTICS_BT601, + SDL_MATRIX_COEFFICIENTS_BT601, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_BT709_LIMITED = 0x21100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_LIMITED, + SDL_COLOR_PRIMARIES_BT709, + SDL_TRANSFER_CHARACTERISTICS_BT709, + SDL_MATRIX_COEFFICIENTS_BT709, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_BT709_FULL = 0x22100421u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P709 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT709, + SDL_TRANSFER_CHARACTERISTICS_BT709, + SDL_MATRIX_COEFFICIENTS_BT709, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_BT2020_LIMITED = 0x21102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_STUDIO_G22_LEFT_P2020 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_LIMITED, + SDL_COLOR_PRIMARIES_BT2020, + SDL_TRANSFER_CHARACTERISTICS_PQ, + SDL_MATRIX_COEFFICIENTS_BT2020_NCL, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, + SDL_COLOR_RANGE_FULL, + SDL_COLOR_PRIMARIES_BT2020, + SDL_TRANSFER_CHARACTERISTICS_PQ, + SDL_MATRIX_COEFFICIENTS_BT2020_NCL, + SDL_CHROMA_LOCATION_LEFT), */ + + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ +} SDL_Colorspace; + +/** + * A structure that represents a color as RGBA components. + * + * The bits of this structure can be directly reinterpreted as an + * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format + * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and + * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Color +{ + Uint8 r; + Uint8 g; + Uint8 b; + Uint8 a; +} SDL_Color; + +/** + * The bits of this structure can be directly reinterpreted as a float-packed + * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_FColor +{ + float r; + float g; + float b; + float a; +} SDL_FColor; + +/** + * A set of indexed colors representing a palette. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetPaletteColors + */ +typedef struct SDL_Palette +{ + int ncolors; /**< number of elements in `colors`. */ + SDL_Color *colors; /**< an array of colors, `ncolors` long. */ + Uint32 version; /**< internal use only, do not touch. */ + int refcount; /**< internal use only, do not touch. */ +} SDL_Palette; + +/** + * Details about the format of a pixel. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_PixelFormatDetails +{ + SDL_PixelFormat format; + Uint8 bits_per_pixel; + Uint8 bytes_per_pixel; + Uint8 padding[2]; + Uint32 Rmask; + Uint32 Gmask; + Uint32 Bmask; + Uint32 Amask; + Uint8 Rbits; + Uint8 Gbits; + Uint8 Bbits; + Uint8 Abits; + Uint8 Rshift; + Uint8 Gshift; + Uint8 Bshift; + Uint8 Ashift; +} SDL_PixelFormatDetails; + +/** + * Get the human readable name of a pixel format. + * + * \param format the pixel format to query. + * \returns the human readable name of the specified pixel format or + * "SDL_PIXELFORMAT_UNKNOWN" if the format isn't recognized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); + +/** + * Convert one of the enumerated pixel formats to a bpp value and RGBA masks. + * + * \param format one of the SDL_PixelFormat values. + * \param bpp a bits per pixel value; usually 15, 16, or 32. + * \param Rmask a pointer filled in with the red mask for the format. + * \param Gmask a pointer filled in with the green mask for the format. + * \param Bmask a pointer filled in with the blue mask for the format. + * \param Amask a pointer filled in with the alpha mask for the format. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPixelFormatForMasks + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); + +/** + * Convert a bpp value and RGBA masks to an enumerated pixel format. + * + * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't + * possible. + * + * \param bpp a bits per pixel value; usually 15, 16, or 32. + * \param Rmask the red mask for the format. + * \param Gmask the green mask for the format. + * \param Bmask the blue mask for the format. + * \param Amask the alpha mask for the format. + * \returns the SDL_PixelFormat value corresponding to the format masks, or + * SDL_PIXELFORMAT_UNKNOWN if there isn't a match. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMasksForPixelFormat + */ +extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); + +/** + * Create an SDL_PixelFormatDetails structure corresponding to a pixel format. + * + * Returned structure may come from a shared global cache (i.e. not newly + * allocated), and hence should not be modified, especially the palette. Weird + * errors such as `Blit combination not supported` may occur. + * + * \param format one of the SDL_PixelFormat values. + * \returns a pointer to a SDL_PixelFormatDetails structure or NULL on + * failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); + +/** + * Create a palette structure with the specified number of color entries. + * + * The palette entries are initialized to white. + * + * \param ncolors represents the number of color entries in the color palette. + * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if + * there wasn't enough memory); call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyPalette + * \sa SDL_SetPaletteColors + * \sa SDL_SetSurfacePalette + */ +extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); + +/** + * Set a range of colors in a palette. + * + * \param palette the SDL_Palette structure to modify. + * \param colors an array of SDL_Color structures to copy into the palette. + * \param firstcolor the index of the first palette entry to modify. + * \param ncolors the number of entries to modify. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified or destroyed in another thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); + +/** + * Free a palette created with SDL_CreatePalette(). + * + * \param palette the SDL_Palette structure to be freed. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified or destroyed in another thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreatePalette + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); + +/** + * Map an RGB triple to an opaque pixel value for a given pixel format. + * + * This function maps the RGB color value to the specified pixel format and + * returns the pixel value best approximating the given RGB color value for + * the given pixel format. + * + * If the format has a palette (8-bit) the index of the closest matching color + * in the palette will be returned. + * + * If the specified pixel format has an alpha component it will be returned as + * all 1 bits (fully opaque). + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param format a pointer to SDL_PixelFormatDetails describing the pixel + * format. + * \param palette an optional palette for indexed formats, may be NULL. + * \param r the red component of the pixel in the range 0-255. + * \param g the green component of the pixel in the range 0-255. + * \param b the blue component of the pixel in the range 0-255. + * \returns a pixel value. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPixelFormatDetails + * \sa SDL_GetRGB + * \sa SDL_MapRGBA + * \sa SDL_MapSurfaceRGB + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b); + +/** + * Map an RGBA quadruple to a pixel value for a given pixel format. + * + * This function maps the RGBA color value to the specified pixel format and + * returns the pixel value best approximating the given RGBA color value for + * the given pixel format. + * + * If the specified pixel format has no alpha component the alpha value will + * be ignored (as it will be in formats with a palette). + * + * If the format has a palette (8-bit) the index of the closest matching color + * in the palette will be returned. + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param format a pointer to SDL_PixelFormatDetails describing the pixel + * format. + * \param palette an optional palette for indexed formats, may be NULL. + * \param r the red component of the pixel in the range 0-255. + * \param g the green component of the pixel in the range 0-255. + * \param b the blue component of the pixel in the range 0-255. + * \param a the alpha component of the pixel in the range 0-255. + * \returns a pixel value. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPixelFormatDetails + * \sa SDL_GetRGBA + * \sa SDL_MapRGB + * \sa SDL_MapSurfaceRGBA + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a); + +/** + * Get RGB values from a pixel in the specified format. + * + * This function uses the entire 8-bit [0..255] range when converting color + * components from pixel formats with less than 8-bits per RGB component + * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, + * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). + * + * \param pixel a pixel value. + * \param format a pointer to SDL_PixelFormatDetails describing the pixel + * format. + * \param palette an optional palette for indexed formats, may be NULL. + * \param r a pointer filled in with the red component, may be NULL. + * \param g a pointer filled in with the green component, may be NULL. + * \param b a pointer filled in with the blue component, may be NULL. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPixelFormatDetails + * \sa SDL_GetRGBA + * \sa SDL_MapRGB + * \sa SDL_MapRGBA + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b); + +/** + * Get RGBA values from a pixel in the specified format. + * + * This function uses the entire 8-bit [0..255] range when converting color + * components from pixel formats with less than 8-bits per RGB component + * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, + * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). + * + * If the surface has no alpha component, the alpha will be returned as 0xff + * (100% opaque). + * + * \param pixel a pixel value. + * \param format a pointer to SDL_PixelFormatDetails describing the pixel + * format. + * \param palette an optional palette for indexed formats, may be NULL. + * \param r a pointer filled in with the red component, may be NULL. + * \param g a pointer filled in with the green component, may be NULL. + * \param b a pointer filled in with the blue component, may be NULL. + * \param a a pointer filled in with the alpha component, may be NULL. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the palette is not modified. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPixelFormatDetails + * \sa SDL_GetRGB + * \sa SDL_MapRGB + * \sa SDL_MapRGBA + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_pixels_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform.h new file mode 100644 index 0000000000..e40f009bad --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform.h @@ -0,0 +1,64 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryPlatform + * + * SDL provides a means to identify the app's platform, both at compile time + * and runtime. + */ + +#ifndef SDL_platform_h_ +#define SDL_platform_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Get the name of the platform. + * + * Here are the names returned for some (but not all) supported platforms: + * + * - "Windows" + * - "macOS" + * - "Linux" + * - "iOS" + * - "Android" + * + * \returns the name of the platform. If the correct platform name is not + * available, returns a string beginning with the text "Unknown". + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_platform_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform_defines.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform_defines.h new file mode 100644 index 0000000000..6b240a8be4 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_platform_defines.h @@ -0,0 +1,476 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: Platform */ + +/* + * SDL_platform_defines.h tries to get a standard set of platform defines. + */ + +#ifndef SDL_platform_defines_h_ +#define SDL_platform_defines_h_ + +#ifdef _AIX + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 +#endif + +#ifdef __HAIKU__ + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 +#endif + +#if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 +#endif + +#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_FREEBSD 1 +#endif + +#if defined(hpux) || defined(__hpux) || defined(__hpux__) + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 +#endif + +#if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 +#endif + +#if (defined(linux) || defined(__linux) || defined(__linux__)) + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 +#endif + +#if defined(ANDROID) || defined(__ANDROID__) + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX +#endif + +#if defined(__unix__) || defined(__unix) || defined(unix) + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 +#endif + +#ifdef __APPLE__ + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + +/* lets us know what version of macOS we're compiling on */ +#include +#ifndef __has_extension /* Older compilers don't support this */ + #define __has_extension(x) 0 + #include + #undef __has_extension +#else + #include +#endif + +/* Fix building with older SDKs that don't define these + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets +*/ +#ifndef TARGET_OS_MACCATALYST + #define TARGET_OS_MACCATALYST 0 +#endif +#ifndef TARGET_OS_IOS + #define TARGET_OS_IOS 0 +#endif +#ifndef TARGET_OS_IPHONE + #define TARGET_OS_IPHONE 0 +#endif +#ifndef TARGET_OS_TV + #define TARGET_OS_TV 0 +#endif +#ifndef TARGET_OS_SIMULATOR + #define TARGET_OS_SIMULATOR 0 +#endif +#ifndef TARGET_OS_VISION + #define TARGET_OS_VISION 0 +#endif + +#if TARGET_OS_TV + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 +#endif + +#if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_VISIONOS 1 +#endif + +#if TARGET_OS_IPHONE + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + +#else + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + +#if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 + #error SDL for macOS only supports deploying on 10.7 and above. +#endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ +#endif /* TARGET_OS_IPHONE */ +#endif /* defined(__APPLE__) */ + +#ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_EMSCRIPTEN 1 +#endif + +#ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_NETBSD 1 +#endif + +#ifdef __OpenBSD__ + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 +#endif + +#if defined(__OS2__) || defined(__EMX__) + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 +#endif + +#if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 +#endif + +#ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_QNXNTO 1 +#endif + +#if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_RISCOS 1 +#endif + +#if defined(__sun) && defined(__SVR4) + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 +#endif + +#if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_CYGWIN 1 +#endif + +#if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 + +/* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ +#if defined(_MSC_VER) && defined(__has_include) + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif + + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ +#elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ + #define HAVE_WINAPIFAMILY_H 1 +#else + #define HAVE_WINAPIFAMILY_H 0 +#endif + +#if HAVE_WINAPIFAMILY_H + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) +#else + #define WINAPI_FAMILY_WINRT 0 +#endif /* 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.2.0. + */ +#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) +#else + #define SDL_WINAPI_FAMILY_PHONE 0 +#endif + +#if WINAPI_FAMILY_WINRT +#error Windows RT/UWP is no longer supported in SDL + +#elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WINGDK 1 + +#elif defined(_GAMING_XBOX_XBOXONE) + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + +#elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXSERIES 1 + +#else + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + +#endif +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + + +/* This is to support generic "any GDK" separate from a platform-specific GDK */ +#if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 +#endif + +#if defined(__PSP__) || defined(__psp__) + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 +#endif + +#if defined(__PS2__) || defined(PS2) + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 +#endif + +#if defined(__vita__) || defined(__psp2__) + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 +#endif + +#ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 +#endif + +#endif /* SDL_platform_defines_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_power.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_power.h similarity index 58% rename from code/thirdparty/SDL2-2.32.8/include/SDL_power.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_power.h index 755c5d42a3..694fb0924d 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_power.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_power.h @@ -25,12 +25,22 @@ /** * # CategoryPower * - * Header for the SDL power management routines. + * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ -#include "SDL_stdinc.h" +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -38,9 +48,14 @@ extern "C" { /** * The basic state for the system's power supply. + * + * These are results returned by SDL_GetPowerInfo(). + * + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { + SDL_POWERSTATE_ERROR = -1, /**< error determining power status */ SDL_POWERSTATE_UNKNOWN, /**< cannot determine power status */ SDL_POWERSTATE_ON_BATTERY, /**< Not plugged in, running on the battery */ SDL_POWERSTATE_NO_BATTERY, /**< Plugged in, no battery available */ @@ -64,24 +79,28 @@ typedef enum SDL_PowerState * It's possible a platform can only report battery percentage or time left * but not both. * - * \param seconds seconds of battery life left, you can pass a NULL here if - * you don't care, will return -1 if we can't determine a - * value, or we're not running on a battery. - * \param percent percentage of battery life left, between 0 and 100, you can - * pass a NULL here if you don't care, will return -1 if we - * can't determine a value, or we're not running on a battery. - * \returns an SDL_PowerState enum representing the current battery state. + * On some platforms, retrieving power supply details might be expensive. If + * you want to display continuous status you could call this function every + * minute or so. + * + * \param seconds a pointer filled in with the seconds of battery life left, + * or NULL to ignore. This will be filled in with -1 if we + * can't determine a value or there is no battery. + * \param percent a pointer filled in with the percentage of battery life + * left, between 0 and 100, or NULL to ignore. This will be + * filled in with -1 we can't determine a value or there is no + * battery. + * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.0. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); +extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_power_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_process.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_process.h new file mode 100644 index 0000000000..511b2f9c51 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process * SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * 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_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes to, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes to, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process * SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_properties.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_properties.h new file mode 100644 index 0000000000..1f47d5f4ad --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_properties.h @@ -0,0 +1,543 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryProperties + * + * A property is a variable that can be created and retrieved by name at + * runtime. + * + * All properties are part of a property group (SDL_PropertiesID). A property + * group can be created with the SDL_CreateProperties function and destroyed + * with the SDL_DestroyProperties function. + * + * Properties can be added to and retrieved from a property group through the + * following functions: + * + * - SDL_SetPointerProperty and SDL_GetPointerProperty operate on `void*` + * pointer types. + * - SDL_SetStringProperty and SDL_GetStringProperty operate on string types. + * - SDL_SetNumberProperty and SDL_GetNumberProperty operate on signed 64-bit + * integer types. + * - SDL_SetFloatProperty and SDL_GetFloatProperty operate on floating point + * types. + * - SDL_SetBooleanProperty and SDL_GetBooleanProperty operate on boolean + * types. + * + * Properties can be removed from a group by using SDL_ClearProperty. + */ + + +#ifndef SDL_properties_h_ +#define SDL_properties_h_ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * SDL properties ID + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_PropertiesID; + +/** + * SDL property type + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_PropertyType +{ + SDL_PROPERTY_TYPE_INVALID, + SDL_PROPERTY_TYPE_POINTER, + SDL_PROPERTY_TYPE_STRING, + SDL_PROPERTY_TYPE_NUMBER, + SDL_PROPERTY_TYPE_FLOAT, + SDL_PROPERTY_TYPE_BOOLEAN +} SDL_PropertyType; + +/** + * Get the global SDL properties. + * + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); + +/** + * Create a group of properties. + * + * All properties are automatically destroyed when SDL_Quit() is called. + * + * \returns an ID for a new group of properties, or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); + +/** + * Copy a group of properties. + * + * Copy all the properties from one group of properties to another, with the + * exception of properties requiring cleanup (set using + * SDL_SetPointerPropertyWithCleanup()), which will not be copied. Any + * property that already exists on `dst` will be overwritten. + * + * \param src the properties to copy. + * \param dst the destination properties. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); + +/** + * Lock a group of properties. + * + * Obtain a multi-threaded lock for these properties. Other threads will wait + * while trying to lock these properties until they are unlocked. Properties + * must be unlocked before they are destroyed. + * + * The lock is automatically taken when setting individual properties, this + * function is only needed when you want to set several properties atomically + * or want to guarantee that properties being queried aren't freed in another + * thread. + * + * \param props the properties to lock. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnlockProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); + +/** + * Unlock a group of properties. + * + * \param props the properties to unlock. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); + +/** + * A callback used to free resources when a property is deleted. + * + * This should release any resources associated with `value` that are no + * longer needed. + * + * This callback is set per-property. Different properties in the same group + * can have different cleanup callbacks. + * + * This callback will be called _during_ SDL_SetPointerPropertyWithCleanup if + * the function fails for any reason. + * + * \param userdata an app-defined pointer passed to the callback. + * \param value the pointer assigned to the property to clean up. + * + * \threadsafety This callback may fire without any locks held; if this is a + * concern, the app should provide its own locking. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetPointerPropertyWithCleanup + */ +typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value); + +/** + * Set a pointer property in a group of properties with a cleanup function + * that is called when the property is deleted. + * + * The cleanup function is also called if setting the property fails for any + * reason. + * + * For simply setting basic data types, like numbers, bools, or strings, use + * SDL_SetNumberProperty, SDL_SetBooleanProperty, or SDL_SetStringProperty + * instead, as those functions will handle cleanup on your behalf. This + * function is only for more complex, custom data. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property, or NULL to delete the property. + * \param cleanup the function to call when this property is deleted, or NULL + * if no cleanup is necessary. + * \param userdata a pointer that is passed to the cleanup function. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPointerProperty + * \sa SDL_SetPointerProperty + * \sa SDL_CleanupPropertyCallback + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); + +/** + * Set a pointer property in a group of properties. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property, or NULL to delete the property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPointerProperty + * \sa SDL_HasProperty + * \sa SDL_SetBooleanProperty + * \sa SDL_SetFloatProperty + * \sa SDL_SetNumberProperty + * \sa SDL_SetPointerPropertyWithCleanup + * \sa SDL_SetStringProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); + +/** + * Set a string property in a group of properties. + * + * This function makes a copy of the string; the caller does not have to + * preserve the data after this call completes. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property, or NULL to delete the property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetStringProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); + +/** + * Set an integer property in a group of properties. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumberProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); + +/** + * Set a floating point property in a group of properties. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetFloatProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); + +/** + * Set a boolean property in a group of properties. + * + * \param props the properties to modify. + * \param name the name of the property to modify. + * \param value the new value of the property. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetBooleanProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); + +/** + * Return whether a property exists in a group of properties. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \returns true if the property exists, or false if it doesn't. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPropertyType + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); + +/** + * Get the type of a property in a group of properties. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is + * not set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasProperty + */ +extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name); + +/** + * Get a pointer property from a group of properties. + * + * By convention, the names of properties that SDL exposes on objects will + * start with "SDL.", and properties that SDL uses internally will start with + * "SDL.internal.". These should be considered read-only and should not be + * modified by applications. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \param default_value the default value of the property. + * \returns the value of the property, or `default_value` if it is not set or + * not a pointer property. + * + * \threadsafety It is safe to call this function from any thread, although + * the data returned is not protected and could potentially be + * freed if you call SDL_SetPointerProperty() or + * SDL_ClearProperty() on these properties from another thread. + * If you need to avoid this, use SDL_LockProperties() and + * SDL_UnlockProperties(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetBooleanProperty + * \sa SDL_GetFloatProperty + * \sa SDL_GetNumberProperty + * \sa SDL_GetPropertyType + * \sa SDL_GetStringProperty + * \sa SDL_HasProperty + * \sa SDL_SetPointerProperty + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props, const char *name, void *default_value); + +/** + * Get a string property from a group of properties. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \param default_value the default value of the property. + * \returns the value of the property, or `default_value` if it is not set or + * not a string property. + * + * \threadsafety It is safe to call this function from any thread, although + * the data returned is not protected and could potentially be + * freed if you call SDL_SetStringProperty() or + * SDL_ClearProperty() on these properties from another thread. + * If you need to avoid this, use SDL_LockProperties() and + * SDL_UnlockProperties(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPropertyType + * \sa SDL_HasProperty + * \sa SDL_SetStringProperty + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value); + +/** + * Get a number property from a group of properties. + * + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a number property. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \param default_value the default value of the property. + * \returns the value of the property, or `default_value` if it is not set or + * not a number property. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPropertyType + * \sa SDL_HasProperty + * \sa SDL_SetNumberProperty + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value); + +/** + * Get a floating point property from a group of properties. + * + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a floating point property. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \param default_value the default value of the property. + * \returns the value of the property, or `default_value` if it is not set or + * not a float property. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPropertyType + * \sa SDL_HasProperty + * \sa SDL_SetFloatProperty + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value); + +/** + * Get a boolean property from a group of properties. + * + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a boolean property. + * + * \param props the properties to query. + * \param name the name of the property to query. + * \param default_value the default value of the property. + * \returns the value of the property, or `default_value` if it is not set or + * not a boolean property. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPropertyType + * \sa SDL_HasProperty + * \sa SDL_SetBooleanProperty + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); + +/** + * Clear a property from a group of properties. + * + * \param props the properties to modify. + * \param name the name of the property to clear. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); + +/** + * A callback used to enumerate all the properties in a group of properties. + * + * This callback is called from SDL_EnumerateProperties(), and is called once + * per property in the set. + * + * \param userdata an app-defined pointer passed to the callback. + * \param props the SDL_PropertiesID that is being enumerated. + * \param name the next property name in the enumeration. + * + * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this + * callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateProperties + */ +typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name); + +/** + * Enumerate the properties contained in a group of properties. + * + * The callback function is called for each property in the group of + * properties. The properties are locked during enumeration. + * + * \param props the properties to query. + * \param callback the function to call for each property. + * \param userdata a pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); + +/** + * Destroy a group of properties. + * + * All properties are deleted and their cleanup functions will be called, if + * any. + * + * \param props the properties to destroy. + * + * \threadsafety This function should not be called while these properties are + * locked or other threads might be setting or getting values + * from these properties. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProperties(SDL_PropertiesID props); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_properties_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_rect.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_rect.h new file mode 100644 index 0000000000..eb2d34a69a --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_rect.h @@ -0,0 +1,507 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryRect + * + * Some helper functions for managing rectangles and 2D points, in both + * integer and floating point versions. + */ + +#ifndef SDL_rect_h_ +#define SDL_rect_h_ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The structure that defines a point (using integers). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetRectEnclosingPoints + * \sa SDL_PointInRect + */ +typedef struct SDL_Point +{ + int x; + int y; +} SDL_Point; + +/** + * The structure that defines a point (using floating point values). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetRectEnclosingPointsFloat + * \sa SDL_PointInRectFloat + */ +typedef struct SDL_FPoint +{ + float x; + float y; +} SDL_FPoint; + + +/** + * A rectangle, with the origin at the upper left (using integers). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_RectEmpty + * \sa SDL_RectsEqual + * \sa SDL_HasRectIntersection + * \sa SDL_GetRectIntersection + * \sa SDL_GetRectAndLineIntersection + * \sa SDL_GetRectUnion + * \sa SDL_GetRectEnclosingPoints + */ +typedef struct SDL_Rect +{ + int x, y; + int w, h; +} SDL_Rect; + + +/** + * A rectangle, with the origin at the upper left (using floating point + * values). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_RectEmptyFloat + * \sa SDL_RectsEqualFloat + * \sa SDL_RectsEqualEpsilon + * \sa SDL_HasRectIntersectionFloat + * \sa SDL_GetRectIntersectionFloat + * \sa SDL_GetRectAndLineIntersectionFloat + * \sa SDL_GetRectUnionFloat + * \sa SDL_GetRectEnclosingPointsFloat + * \sa SDL_PointInRectFloat + */ +typedef struct SDL_FRect +{ + float x; + float y; + float w; + float h; +} SDL_FRect; + + +/** + * Convert an SDL_Rect to SDL_FRect + * + * \param rect a pointer to an SDL_Rect. + * \param frect a pointer filled in with the floating point representation of + * `rect`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) +{ + frect->x = (float)rect->x; + frect->y = (float)rect->y; + frect->w = (float)rect->w; + frect->h = (float)rect->h; +} + +/** + * Determine whether a point resides inside a rectangle. + * + * A point is considered part of a rectangle if both `p` and `r` are not NULL, + * and `p`'s x and y coordinates are >= to the rectangle's top left corner, + * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0) + * as "inside" and (0,1) as not. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param p the point to test. + * \param r the rectangle to test. + * \returns true if `p` is contained by `r`, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +{ + return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; +} + +/** + * Determine whether a rectangle has no area. + * + * A rectangle is considered "empty" for this function if `r` is NULL, or if + * `r`'s width and/or height are <= 0. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param r the rectangle to test. + * \returns true if the rectangle is "empty", false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) +{ + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; +} + +/** + * Determine whether two rectangles are equal. + * + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height match. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param a the first rectangle to test. + * \param b the second rectangle to test. + * \returns true if the rectangles are equal, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +{ + return (a && b && (a->x == b->x) && (a->y == b->y) && + (a->w == b->w) && (a->h == b->h)) ? true : false; +} + +/** + * Determine whether two rectangles intersect. + * + * If either pointer is NULL the function will return false. + * + * \param A an SDL_Rect structure representing the first rectangle. + * \param B an SDL_Rect structure representing the second rectangle. + * \returns true if there is an intersection, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRectIntersection + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); + +/** + * Calculate the intersection of two rectangles. + * + * If `result` is NULL then this function will return false. + * + * \param A an SDL_Rect structure representing the first rectangle. + * \param B an SDL_Rect structure representing the second rectangle. + * \param result an SDL_Rect structure filled in with the intersection of + * rectangles `A` and `B`. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasRectIntersection + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); + +/** + * Calculate the union of two rectangles. + * + * \param A an SDL_Rect structure representing the first rectangle. + * \param B an SDL_Rect structure representing the second rectangle. + * \param result an SDL_Rect structure filled in with the union of rectangles + * `A` and `B`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); + +/** + * Calculate a minimal rectangle enclosing a set of points. + * + * If `clip` is not NULL then only points inside of the clipping rectangle are + * considered. + * + * \param points an array of SDL_Point structures representing points to be + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_Rect used for clipping or NULL to enclose all points. + * \param result an SDL_Rect structure filled in with the minimal enclosing + * rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); + +/** + * Calculate the intersection of a rectangle and line segment. + * + * This function is used to clip a line segment to a rectangle. A line segment + * contained entirely within the rectangle or that does not intersect will + * remain unchanged. A line segment that crosses the rectangle at either or + * both ends will be clipped to the boundary of the rectangle and the new + * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. + * + * \param rect an SDL_Rect structure representing the rectangle to intersect. + * \param X1 a pointer to the starting X-coordinate of the line. + * \param Y1 a pointer to the starting Y-coordinate of the line. + * \param X2 a pointer to the ending X-coordinate of the line. + * \param Y2 a pointer to the ending Y-coordinate of the line. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); + + +/* SDL_FRect versions... */ + +/** + * Determine whether a point resides inside a floating point rectangle. + * + * A point is considered part of a rectangle if both `p` and `r` are not NULL, + * and `p`'s x and y coordinates are >= to the rectangle's top left corner, + * and <= the rectangle's x+w and y+h. So a 1x1 rectangle considers point + * (0,0) and (0,1) as "inside" and (0,2) as not. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param p the point to test. + * \param r the rectangle to test. + * \returns true if `p` is contained by `r`, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +{ + return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; +} + +/** + * Determine whether a floating point rectangle can contain any point. + * + * A rectangle is considered "empty" for this function if `r` is NULL, or if + * `r`'s width and/or height are < 0.0f. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param r the rectangle to test. + * \returns true if the rectangle is "empty", false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) +{ + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; +} + +/** + * Determine whether two floating point rectangles are equal, within some + * given epsilon. + * + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height are within `epsilon` of each other. If you don't know + * what value to use for `epsilon`, you should call the SDL_RectsEqualFloat + * function instead. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param a the first rectangle to test. + * \param b the second rectangle to test. + * \param epsilon the epsilon value for comparison. + * \returns true if the rectangles are equal, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RectsEqualFloat + */ +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, float epsilon) +{ + return (a && b && ((a == b) || + ((SDL_fabsf(a->x - b->x) <= epsilon) && + (SDL_fabsf(a->y - b->y) <= epsilon) && + (SDL_fabsf(a->w - b->w) <= epsilon) && + (SDL_fabsf(a->h - b->h) <= epsilon)))) + ? true : false; +} + +/** + * Determine whether two floating point rectangles are equal, within a default + * epsilon. + * + * Rectangles are considered equal if both are not NULL and each of their x, + * y, width and height are within SDL_FLT_EPSILON of each other. This is often + * a reasonable way to compare two floating point rectangles and deal with the + * slight precision variations in floating point calculations that tend to pop + * up. + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param a the first rectangle to test. + * \param b the second rectangle to test. + * \returns true if the rectangles are equal, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RectsEqualEpsilon + */ +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +{ + return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); +} + +/** + * Determine whether two rectangles intersect with float precision. + * + * If either pointer is NULL the function will return false. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRectIntersection + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); + +/** + * Calculate the intersection of two rectangles with float precision. + * + * If `result` is NULL then this function will return false. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \param result an SDL_FRect structure filled in with the intersection of + * rectangles `A` and `B`. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasRectIntersectionFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); + +/** + * Calculate the union of two rectangles with float precision. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \param result an SDL_FRect structure filled in with the union of rectangles + * `A` and `B`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); + +/** + * Calculate a minimal rectangle enclosing a set of points with float + * precision. + * + * If `clip` is not NULL then only points inside of the clipping rectangle are + * considered. + * + * \param points an array of SDL_FPoint structures representing points to be + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_FRect used for clipping or NULL to enclose all points. + * \param result an SDL_FRect structure filled in with the minimal enclosing + * rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); + +/** + * Calculate the intersection of a rectangle and line segment with float + * precision. + * + * This function is used to clip a line segment to a rectangle. A line segment + * contained entirely within the rectangle or that does not intersect will + * remain unchanged. A line segment that crosses the rectangle at either or + * both ends will be clipped to the boundary of the rectangle and the new + * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. + * + * \param rect an SDL_FRect structure representing the rectangle to intersect. + * \param X1 a pointer to the starting X-coordinate of the line. + * \param Y1 a pointer to the starting Y-coordinate of the line. + * \param X2 a pointer to the ending X-coordinate of the line. + * \param Y2 a pointer to the ending Y-coordinate of the line. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_rect_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_render.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_render.h new file mode 100644 index 0000000000..c9d184cc07 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_render.h @@ -0,0 +1,2645 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryRender + * + * Header file for SDL 2D rendering functions. + * + * This API supports the following features: + * + * - single pixel points + * - single pixel lines + * - filled rectangles + * - texture images + * - 2D polygons + * + * The primitives may be drawn in opaque, blended, or additive modes. + * + * The texture images may be drawn in opaque, blended, or additive modes. They + * can have an additional color tint or alpha modulation applied to them, and + * may also be stretched with linear interpolation. + * + * This API is designed to accelerate simple 2D operations. You may want more + * functionality such as polygons and particle effects and in that case you + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. + * + * These functions must be called from the main thread. See this bug for + * details: https://github.com/libsdl-org/SDL/issues/986 + */ + +#ifndef SDL_render_h_ +#define SDL_render_h_ + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The name of the software renderer. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SOFTWARE_RENDERER "software" + +/** + * Vertex structure. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Vertex +{ + SDL_FPoint position; /**< Vertex position, in SDL_Renderer coordinates */ + SDL_FColor color; /**< Vertex color */ + SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */ +} SDL_Vertex; + +/** + * The access pattern allowed for a texture. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_TextureAccess +{ + SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */ + SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */ + SDL_TEXTUREACCESS_TARGET /**< Texture can be used as a render target */ +} SDL_TextureAccess; + +/** + * How the logical size is mapped to the output. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_RendererLogicalPresentation +{ + SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */ + SDL_LOGICAL_PRESENTATION_STRETCH, /**< The rendered content is stretched to the output resolution */ + SDL_LOGICAL_PRESENTATION_LETTERBOX, /**< The rendered content is fit to the largest dimension and the other dimension is letterboxed with black bars */ + SDL_LOGICAL_PRESENTATION_OVERSCAN, /**< The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds */ + SDL_LOGICAL_PRESENTATION_INTEGER_SCALE /**< The rendered content is scaled up by integer multiples to fit the output resolution */ +} SDL_RendererLogicalPresentation; + +/** + * A structure representing rendering state + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Renderer SDL_Renderer; + +#ifndef SDL_INTERNAL + +/** + * An efficient driver-specific representation of pixel data + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture + */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + +typedef struct SDL_Texture SDL_Texture; + +/* Function prototypes */ + +/** + * Get the number of 2D rendering drivers available for the current display. + * + * A render driver is a set of code that handles rendering and texture + * management on a particular display. Normally there is only one, but some + * drivers may have several available with different capabilities. + * + * There may be none if SDL was compiled without render support. + * + * \returns the number of built in render drivers. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRenderer + * \sa SDL_GetRenderDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); + +/** + * Use this function to get the name of a built in 2D rendering driver. + * + * The list of rendering drivers is given in the order that they are normally + * initialized by default; the drivers that seem more reasonable to choose + * first (as far as the SDL developers believe) are earlier in the list. + * + * The names of drivers are all simple, low-ASCII identifiers, like "opengl", + * "direct3d12" or "metal". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of the rendering driver; the value ranges from 0 to + * SDL_GetNumRenderDrivers() - 1. + * \returns the name of the rendering driver at the requested index, or NULL + * if an invalid index was specified. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumRenderDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); + +/** + * Create a window and default renderer. + * + * \param title the title of the window, in UTF-8 encoding. + * \param width the width of the window. + * \param height the height of the window. + * \param window_flags the flags used to create the window (see + * SDL_CreateWindow()). + * \param window a pointer filled with the window, or NULL on error. + * \param renderer a pointer filled with the renderer, or NULL on error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRenderer + * \sa SDL_CreateWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); + +/** + * Create a 2D rendering context for a window. + * + * If you want a specific renderer, you can specify its name here. A list of + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. + * + * By default the rendering size matches the window size in pixels, but you + * can call SDL_SetRenderLogicalPresentation() to change the content size and + * scaling options. + * + * \param window the window where rendering is displayed. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRendererWithProperties + * \sa SDL_CreateSoftwareRenderer + * \sa SDL_DestroyRenderer + * \sa SDL_GetNumRenderDrivers + * \sa SDL_GetRenderDriver + * \sa SDL_GetRendererName + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, const char *name); + +/** + * Create a 2D rendering context for a window, with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_RENDERER_CREATE_NAME_STRING`: the name of the rendering driver + * to use, if a specific one is desired + * - `SDL_PROP_RENDERER_CREATE_WINDOW_POINTER`: the window where rendering is + * displayed, required if this isn't a software renderer using a surface + * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering + * is displayed, if you want a software renderer without a window + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace + * value describing the colorspace for output to the display, defaults to + * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers + * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and + * supports HDR output. If you select SDL_COLORSPACE_SRGB_LINEAR, drawing + * still uses the sRGB colorspace, but values can go beyond 1.0 and float + * (linear) format textures can be used for HDR content. + * - `SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER`: non-zero if you want + * present synchronized with the refresh rate. This property can take any + * value that is supported by SDL_SetRenderVSync() for the renderer. + * + * With the vulkan renderer: + * + * - `SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER`: the VkInstance to use + * with the renderer, optional. + * - `SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR to use + * with the renderer, optional. + * - `SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER`: the + * VkPhysicalDevice to use with the renderer, optional. + * - `SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER`: the VkDevice to use + * with the renderer, optional. + * - `SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the + * queue family index used for rendering. + * - `SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the + * queue family index used for presentation. + * + * \param props the properties to use. + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProperties + * \sa SDL_CreateRenderer + * \sa SDL_CreateSoftwareRenderer + * \sa SDL_DestroyRenderer + * \sa SDL_GetRendererName + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_RENDERER_CREATE_NAME_STRING "SDL.renderer.create.name" +#define SDL_PROP_RENDERER_CREATE_WINDOW_POINTER "SDL.renderer.create.window" +#define SDL_PROP_RENDERER_CREATE_SURFACE_POINTER "SDL.renderer.create.surface" +#define SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.create.output_colorspace" +#define SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER "SDL.renderer.create.present_vsync" +#define SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER "SDL.renderer.create.vulkan.instance" +#define SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER "SDL.renderer.create.vulkan.surface" +#define SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.create.vulkan.physical_device" +#define SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER "SDL.renderer.create.vulkan.device" +#define SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.graphics_queue_family_index" +#define SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.present_queue_family_index" + +/** + * Create a 2D software rendering context for a surface. + * + * Two other API which can be used to create SDL_Renderer: + * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_ + * create a software renderer, but they are intended to be used with an + * SDL_Window as the final destination and not an SDL_Surface. + * + * \param surface the SDL_Surface structure representing the surface where + * rendering is done. + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyRenderer + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface *surface); + +/** + * Get the renderer associated with a window. + * + * \param window the window to query. + * \returns the rendering context on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); + +/** + * Get the window associated with a renderer. + * + * \param renderer the renderer to query. + * \returns the window on success or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); + +/** + * Get the name of a renderer. + * + * \param renderer the rendering context. + * \returns the name of the selected renderer, or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRenderer + * \sa SDL_CreateRendererWithProperties + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *renderer); + +/** + * Get the properties associated with a renderer. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_RENDERER_NAME_STRING`: the name of the rendering driver + * - `SDL_PROP_RENDERER_WINDOW_POINTER`: the window where rendering is + * displayed, if any + * - `SDL_PROP_RENDERER_SURFACE_POINTER`: the surface where rendering is + * displayed, if this is a software renderer without a window + * - `SDL_PROP_RENDERER_VSYNC_NUMBER`: the current vsync setting + * - `SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER`: the maximum texture width + * and height + * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) + * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, + * representing the available texture formats for this renderer. + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value + * describing the colorspace for output to the display, defaults to + * SDL_COLORSPACE_SRGB. + * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is + * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with + * HDR enabled. This property can change dynamically when + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the + * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is + * automatically multiplied into the color scale. This property can change + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range + * that can be displayed, in terms of the SDR white point. When HDR is not + * enabled, this will be 1.0. This property can change dynamically when + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * + * With the direct3d renderer: + * + * - `SDL_PROP_RENDERER_D3D9_DEVICE_POINTER`: the IDirect3DDevice9 associated + * with the renderer + * + * With the direct3d11 renderer: + * + * - `SDL_PROP_RENDERER_D3D11_DEVICE_POINTER`: the ID3D11Device associated + * with the renderer + * - `SDL_PROP_RENDERER_D3D11_SWAPCHAIN_POINTER`: the IDXGISwapChain1 + * associated with the renderer. This may change when the window is resized. + * + * With the direct3d12 renderer: + * + * - `SDL_PROP_RENDERER_D3D12_DEVICE_POINTER`: the ID3D12Device associated + * with the renderer + * - `SDL_PROP_RENDERER_D3D12_SWAPCHAIN_POINTER`: the IDXGISwapChain4 + * associated with the renderer. + * - `SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER`: the ID3D12CommandQueue + * associated with the renderer + * + * With the vulkan renderer: + * + * - `SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER`: the VkInstance associated + * with the renderer + * - `SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR associated + * with the renderer + * - `SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER`: the VkPhysicalDevice + * associated with the renderer + * - `SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER`: the VkDevice associated with + * the renderer + * - `SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the queue + * family index used for rendering + * - `SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the queue + * family index used for presentation + * - `SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER`: the number of + * swapchain images, or potential frames in flight, used by the Vulkan + * renderer + * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * + * \param renderer the rendering context. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); + +#define SDL_PROP_RENDERER_NAME_STRING "SDL.renderer.name" +#define SDL_PROP_RENDERER_WINDOW_POINTER "SDL.renderer.window" +#define SDL_PROP_RENDERER_SURFACE_POINTER "SDL.renderer.surface" +#define SDL_PROP_RENDERER_VSYNC_NUMBER "SDL.renderer.vsync" +#define SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER "SDL.renderer.max_texture_size" +#define SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER "SDL.renderer.texture_formats" +#define SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.output_colorspace" +#define SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN "SDL.renderer.HDR_enabled" +#define SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT "SDL.renderer.SDR_white_point" +#define SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT "SDL.renderer.HDR_headroom" +#define SDL_PROP_RENDERER_D3D9_DEVICE_POINTER "SDL.renderer.d3d9.device" +#define SDL_PROP_RENDERER_D3D11_DEVICE_POINTER "SDL.renderer.d3d11.device" +#define SDL_PROP_RENDERER_D3D11_SWAPCHAIN_POINTER "SDL.renderer.d3d11.swap_chain" +#define SDL_PROP_RENDERER_D3D12_DEVICE_POINTER "SDL.renderer.d3d12.device" +#define SDL_PROP_RENDERER_D3D12_SWAPCHAIN_POINTER "SDL.renderer.d3d12.swap_chain" +#define SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER "SDL.renderer.d3d12.command_queue" +#define SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER "SDL.renderer.vulkan.instance" +#define SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER "SDL.renderer.vulkan.surface" +#define SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.vulkan.physical_device" +#define SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER "SDL.renderer.vulkan.device" +#define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" +#define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" +#define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" + +/** + * Get the output size in pixels of a rendering context. + * + * This returns the true output size in pixels, ignoring any render targets or + * logical size and presentation. + * + * For the output size of the current rendering target, with logical size + * adjustments, use SDL_GetCurrentRenderOutputSize() instead. + * + * \param renderer the rendering context. + * \param w a pointer filled in with the width in pixels. + * \param h a pointer filled in with the height in pixels. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentRenderOutputSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); + +/** + * Get the current output size in pixels of a rendering context. + * + * If a rendering target is active, this will return the size of the rendering + * target in pixels, otherwise return the value of SDL_GetRenderOutputSize(). + * + * Rendering target or not, the output will be adjusted by the current logical + * presentation state, dictated by SDL_SetRenderLogicalPresentation(). + * + * \param renderer the rendering context. + * \param w a pointer filled in with the current width. + * \param h a pointer filled in with the current height. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderOutputSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); + +/** + * Create a texture for a rendering context. + * + * The contents of a texture when first created are not defined. + * + * \param renderer the rendering context. + * \param format one of the enumerated values in SDL_PixelFormat. + * \param access one of the enumerated values in SDL_TextureAccess. + * \param w the width of the texture in pixels. + * \param h the height of the texture in pixels. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture + * \sa SDL_GetTextureSize + * \sa SDL_UpdateTexture + */ +extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormat format, SDL_TextureAccess access, int w, int h); + +/** + * Create a texture from an existing surface. + * + * The surface is not modified or freed by this function. + * + * The SDL_TextureAccess hint for the created texture is + * `SDL_TEXTUREACCESS_STATIC`. + * + * The pixel format of the created texture may be different from the pixel + * format of the surface, and can be queried using the + * SDL_PROP_TEXTURE_FORMAT_NUMBER property. + * + * \param renderer the rendering context. + * \param surface the SDL_Surface structure containing pixel data used to fill + * the texture. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture + */ +extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *renderer, SDL_Surface *surface); + +/** + * Create a texture for a rendering context with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value + * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR + * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, + * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for + * YUV textures. + * - `SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER`: one of the enumerated values in + * SDL_PixelFormat, defaults to the best RGBA format for the renderer + * - `SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER`: one of the enumerated values in + * SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC + * - `SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER`: the width of the texture in + * pixels, required + * - `SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER`: the height of the texture in + * pixels, required + * - `SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating + * point textures, this defines the value of 100% diffuse white, with higher + * values being displayed in the High Dynamic Range headroom. This defaults + * to 100 for HDR10 textures and 1.0 for floating point textures. + * - `SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT`: for HDR10 and floating + * point textures, this defines the maximum dynamic range used by the + * content, in terms of the SDR white point. This would be equivalent to + * maxCLL / SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT for HDR10 content. + * If this is defined, any values outside the range supported by the display + * will be scaled into the available HDR headroom, otherwise they are + * clipped. + * + * With the direct3d11 renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D + * associated with the U plane of a YUV texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D + * associated with the V plane of a YUV texture, if you want to wrap an + * existing texture. + * + * With the direct3d12 renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER`: the ID3D12Resource + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource + * associated with the U plane of a YUV texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource + * associated with the V plane of a YUV texture, if you want to wrap an + * existing texture. + * + * With the metal renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER`: the CVPixelBufferRef + * associated with the texture, if you want to create a texture from an + * existing pixel buffer. + * + * With the opengl renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER`: the GLuint texture + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture + * associated with the UV plane of an NV12 texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture + * associated with the U plane of a YUV texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture + * associated with the V plane of a YUV texture, if you want to wrap an + * existing texture. + * + * With the opengles2 renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture + * associated with the UV plane of an NV12 texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture + * associated with the U plane of a YUV texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture + * associated with the V plane of a YUV texture, if you want to wrap an + * existing texture. + * + * With the vulkan renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER`: the VkImage with layout + * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL associated with the texture, if + * you want to wrap an existing texture. + * + * \param renderer the rendering context. + * \param props the properties to use. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProperties + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_DestroyTexture + * \sa SDL_GetTextureSize + * \sa SDL_UpdateTexture + */ +extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props); + +#define SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER "SDL.texture.create.colorspace" +#define SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER "SDL.texture.create.format" +#define SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER "SDL.texture.create.access" +#define SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER "SDL.texture.create.width" +#define SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER "SDL.texture.create.height" +#define SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT "SDL.texture.create.SDR_white_point" +#define SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT "SDL.texture.create.HDR_headroom" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "SDL.texture.create.d3d11.texture" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "SDL.texture.create.d3d11.texture_u" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "SDL.texture.create.d3d11.texture_v" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "SDL.texture.create.d3d12.texture" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "SDL.texture.create.d3d12.texture_u" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "SDL.texture.create.d3d12.texture_v" +#define SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER "SDL.texture.create.metal.pixelbuffer" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "SDL.texture.create.opengl.texture" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.create.opengl.texture_uv" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.create.opengl.texture_u" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.create.opengl.texture_v" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.create.opengles2.texture" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.create.opengles2.texture_uv" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.create.opengles2.texture_u" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.create.opengles2.texture_v" +#define SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER "SDL.texture.create.vulkan.texture" + +/** + * Get the properties associated with a texture. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing + * the texture colorspace. + * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in + * SDL_PixelFormat. + * - `SDL_PROP_TEXTURE_ACCESS_NUMBER`: one of the enumerated values in + * SDL_TextureAccess. + * - `SDL_PROP_TEXTURE_WIDTH_NUMBER`: the width of the texture in pixels. + * - `SDL_PROP_TEXTURE_HEIGHT_NUMBER`: the height of the texture in pixels. + * - `SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating point + * textures, this defines the value of 100% diffuse white, with higher + * values being displayed in the High Dynamic Range headroom. This defaults + * to 100 for HDR10 textures and 1.0 for other textures. + * - `SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT`: for HDR10 and floating point + * textures, this defines the maximum dynamic range used by the content, in + * terms of the SDR white point. If this is defined, any values outside the + * range supported by the display will be scaled into the available HDR + * headroom, otherwise they are clipped. This defaults to 1.0 for SDR + * textures, 4.0 for HDR10 textures, and no default for floating point + * textures. + * + * With the direct3d11 renderer: + * + * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D associated + * with the texture + * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D + * associated with the U plane of a YUV texture + * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D + * associated with the V plane of a YUV texture + * + * With the direct3d12 renderer: + * + * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER`: the ID3D12Resource associated + * with the texture + * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource associated + * with the U plane of a YUV texture + * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource associated + * with the V plane of a YUV texture + * + * With the vulkan renderer: + * + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture + * + * With the opengl renderer: + * + * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER`: the GLuint texture associated + * with the texture + * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture + * associated with the UV plane of an NV12 texture + * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture associated + * with the U plane of a YUV texture + * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture associated + * with the V plane of a YUV texture + * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER`: the GLenum for the + * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_RECTANGLE_ARB`, etc) + * - `SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT`: the texture coordinate width of + * the texture (0.0 - 1.0) + * - `SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT`: the texture coordinate height of + * the texture (0.0 - 1.0) + * + * With the opengles2 renderer: + * + * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture + * associated with the texture + * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture + * associated with the UV plane of an NV12 texture + * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture + * associated with the U plane of a YUV texture + * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture + * associated with the V plane of a YUV texture + * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the + * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) + * + * \param texture the texture to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); + +#define SDL_PROP_TEXTURE_COLORSPACE_NUMBER "SDL.texture.colorspace" +#define SDL_PROP_TEXTURE_FORMAT_NUMBER "SDL.texture.format" +#define SDL_PROP_TEXTURE_ACCESS_NUMBER "SDL.texture.access" +#define SDL_PROP_TEXTURE_WIDTH_NUMBER "SDL.texture.width" +#define SDL_PROP_TEXTURE_HEIGHT_NUMBER "SDL.texture.height" +#define SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT "SDL.texture.SDR_white_point" +#define SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT "SDL.texture.HDR_headroom" +#define SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER "SDL.texture.d3d11.texture" +#define SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER "SDL.texture.d3d11.texture_u" +#define SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER "SDL.texture.d3d11.texture_v" +#define SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER "SDL.texture.d3d12.texture" +#define SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER "SDL.texture.d3d12.texture_u" +#define SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER "SDL.texture.d3d12.texture_v" +#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER "SDL.texture.opengl.texture" +#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.opengl.texture_uv" +#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.opengl.texture_u" +#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.opengl.texture_v" +#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER "SDL.texture.opengl.target" +#define SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT "SDL.texture.opengl.tex_w" +#define SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT "SDL.texture.opengl.tex_h" +#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.opengles2.texture" +#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.opengles2.texture_uv" +#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.opengles2.texture_u" +#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.opengles2.texture_v" +#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER "SDL.texture.opengles2.target" +#define SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER "SDL.texture.vulkan.texture" + +/** + * Get the renderer that created an SDL_Texture. + * + * \param texture the texture to query. + * \returns a pointer to the SDL_Renderer that created the texture, or NULL on + * failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); + +/** + * Get the size of a texture, as floating point values. + * + * \param texture the texture to query. + * \param w a pointer filled in with the width of the texture in pixels. This + * argument can be NULL if you don't need this information. + * \param h a pointer filled in with the height of the texture in pixels. This + * argument can be NULL if you don't need this information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); + +/** + * Set an additional color value multiplied into render copy operations. + * + * When this texture is rendered, during the copy operation each source color + * channel is modulated by the appropriate color value according to the + * following formula: + * + * `srcC = srcC * (color / 255)` + * + * Color modulation is not always supported by the renderer; it will return + * false if color modulation is not supported. + * + * \param texture the texture to update. + * \param r the red color value multiplied into copy operations. + * \param g the green color value multiplied into copy operations. + * \param b the blue color value multiplied into copy operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureColorMod + * \sa SDL_SetTextureAlphaMod + * \sa SDL_SetTextureColorModFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); + + +/** + * Set an additional color value multiplied into render copy operations. + * + * When this texture is rendered, during the copy operation each source color + * channel is modulated by the appropriate color value according to the + * following formula: + * + * `srcC = srcC * color` + * + * Color modulation is not always supported by the renderer; it will return + * false if color modulation is not supported. + * + * \param texture the texture to update. + * \param r the red color value multiplied into copy operations. + * \param g the green color value multiplied into copy operations. + * \param b the blue color value multiplied into copy operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureColorModFloat + * \sa SDL_SetTextureAlphaModFloat + * \sa SDL_SetTextureColorMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); + + +/** + * Get the additional color value multiplied into render copy operations. + * + * \param texture the texture to query. + * \param r a pointer filled in with the current red color value. + * \param g a pointer filled in with the current green color value. + * \param b a pointer filled in with the current blue color value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaMod + * \sa SDL_GetTextureColorModFloat + * \sa SDL_SetTextureColorMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); + +/** + * Get the additional color value multiplied into render copy operations. + * + * \param texture the texture to query. + * \param r a pointer filled in with the current red color value. + * \param g a pointer filled in with the current green color value. + * \param b a pointer filled in with the current blue color value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaModFloat + * \sa SDL_GetTextureColorMod + * \sa SDL_SetTextureColorModFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); + +/** + * Set an additional alpha value multiplied into render copy operations. + * + * When this texture is rendered, during the copy operation the source alpha + * value is modulated by this alpha value according to the following formula: + * + * `srcA = srcA * (alpha / 255)` + * + * Alpha modulation is not always supported by the renderer; it will return + * false if alpha modulation is not supported. + * + * \param texture the texture to update. + * \param alpha the source alpha value multiplied into copy operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaMod + * \sa SDL_SetTextureAlphaModFloat + * \sa SDL_SetTextureColorMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); + +/** + * Set an additional alpha value multiplied into render copy operations. + * + * When this texture is rendered, during the copy operation the source alpha + * value is modulated by this alpha value according to the following formula: + * + * `srcA = srcA * alpha` + * + * Alpha modulation is not always supported by the renderer; it will return + * false if alpha modulation is not supported. + * + * \param texture the texture to update. + * \param alpha the source alpha value multiplied into copy operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaModFloat + * \sa SDL_SetTextureAlphaMod + * \sa SDL_SetTextureColorModFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); + +/** + * Get the additional alpha value multiplied into render copy operations. + * + * \param texture the texture to query. + * \param alpha a pointer filled in with the current alpha value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaModFloat + * \sa SDL_GetTextureColorMod + * \sa SDL_SetTextureAlphaMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); + +/** + * Get the additional alpha value multiplied into render copy operations. + * + * \param texture the texture to query. + * \param alpha a pointer filled in with the current alpha value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureAlphaMod + * \sa SDL_GetTextureColorModFloat + * \sa SDL_SetTextureAlphaModFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); + +/** + * Set the blend mode for a texture, used by SDL_RenderTexture(). + * + * If the blend mode is not supported, the closest supported mode is chosen + * and this function returns false. + * + * \param texture the texture to update. + * \param blendMode the SDL_BlendMode to use for texture blending. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); + +/** + * Get the blend mode used for texture copy operations. + * + * \param texture the texture to query. + * \param blendMode a pointer filled in with the current SDL_BlendMode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTextureBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); + +/** + * Set the scale mode used for texture scale operations. + * + * The default texture scale mode is SDL_SCALEMODE_LINEAR. + * + * If the scale mode is not supported, the closest supported mode is chosen. + * + * \param texture the texture to update. + * \param scaleMode the SDL_ScaleMode to use for texture scaling. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTextureScaleMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); + +/** + * Get the scale mode used for texture scale operations. + * + * \param texture the texture to query. + * \param scaleMode a pointer filled in with the current scale mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTextureScaleMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); + +/** + * Update the given texture rectangle with new pixel data. + * + * The pixel data must be in the pixel format of the texture, which can be + * queried using the SDL_PROP_TEXTURE_FORMAT_NUMBER property. + * + * This is a fairly slow function, intended for use with static textures that + * do not change often. + * + * If the texture is intended to be updated often, it is preferred to create + * the texture as streaming and use the locking functions referenced below. + * While this function will work with streaming textures, for optimization + * reasons you may not get the pixels back if you lock the texture afterward. + * + * \param texture the texture to update. + * \param rect an SDL_Rect structure representing the area to update, or NULL + * to update the entire texture. + * \param pixels the raw pixel data in the format of the texture. + * \param pitch the number of bytes in a row of pixel data, including padding + * between lines. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockTexture + * \sa SDL_UnlockTexture + * \sa SDL_UpdateNVTexture + * \sa SDL_UpdateYUVTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); + +/** + * Update a rectangle within a planar YV12 or IYUV texture with new pixel + * data. + * + * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous + * block of Y and U/V planes in the proper order, but this function is + * available if your pixel data is not contiguous. + * + * \param texture the texture to update. + * \param rect a pointer to the rectangle of pixels to update, or NULL to + * update the entire texture. + * \param Yplane the raw pixel data for the Y plane. + * \param Ypitch the number of bytes between rows of pixel data for the Y + * plane. + * \param Uplane the raw pixel data for the U plane. + * \param Upitch the number of bytes between rows of pixel data for the U + * plane. + * \param Vplane the raw pixel data for the V plane. + * \param Vpitch the number of bytes between rows of pixel data for the V + * plane. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UpdateNVTexture + * \sa SDL_UpdateTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, + const SDL_Rect *rect, + const Uint8 *Yplane, int Ypitch, + const Uint8 *Uplane, int Upitch, + const Uint8 *Vplane, int Vpitch); + +/** + * Update a rectangle within a planar NV12 or NV21 texture with new pixels. + * + * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous + * block of NV12/21 planes in the proper order, but this function is available + * if your pixel data is not contiguous. + * + * \param texture the texture to update. + * \param rect a pointer to the rectangle of pixels to update, or NULL to + * update the entire texture. + * \param Yplane the raw pixel data for the Y plane. + * \param Ypitch the number of bytes between rows of pixel data for the Y + * plane. + * \param UVplane the raw pixel data for the UV plane. + * \param UVpitch the number of bytes between rows of pixel data for the UV + * plane. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UpdateTexture + * \sa SDL_UpdateYUVTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, + const SDL_Rect *rect, + const Uint8 *Yplane, int Ypitch, + const Uint8 *UVplane, int UVpitch); + +/** + * Lock a portion of the texture for **write-only** pixel access. + * + * As an optimization, the pixels made available for editing don't necessarily + * contain the old texture data. This is a write-only operation, and if you + * need to keep a copy of the texture data you should do that at the + * application level. + * + * You must use SDL_UnlockTexture() to unlock the pixels and apply any + * changes. + * + * \param texture the texture to lock for access, which was created with + * `SDL_TEXTUREACCESS_STREAMING`. + * \param rect an SDL_Rect structure representing the area to lock for access; + * NULL to lock the entire texture. + * \param pixels this is filled in with a pointer to the locked pixels, + * appropriately offset by the locked area. + * \param pitch this is filled in with the pitch of the locked pixels; the + * pitch is the length of one row in bytes. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockTextureToSurface + * \sa SDL_UnlockTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, + const SDL_Rect *rect, + void **pixels, int *pitch); + +/** + * Lock a portion of the texture for **write-only** pixel access, and expose + * it as a SDL surface. + * + * Besides providing an SDL_Surface instead of raw pixel data, this function + * operates like SDL_LockTexture. + * + * As an optimization, the pixels made available for editing don't necessarily + * contain the old texture data. This is a write-only operation, and if you + * need to keep a copy of the texture data you should do that at the + * application level. + * + * You must use SDL_UnlockTexture() to unlock the pixels and apply any + * changes. + * + * The returned surface is freed internally after calling SDL_UnlockTexture() + * or SDL_DestroyTexture(). The caller should not free it. + * + * \param texture the texture to lock for access, which must be created with + * `SDL_TEXTUREACCESS_STREAMING`. + * \param rect a pointer to the rectangle to lock for access. If the rect is + * NULL, the entire texture will be locked. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockTexture + * \sa SDL_UnlockTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); + +/** + * Unlock a texture, uploading the changes to video memory, if needed. + * + * **Warning**: Please note that SDL_LockTexture() is intended to be + * write-only; it will not guarantee the previous contents of the texture will + * be provided. You must fully initialize any area of a texture that you lock + * before unlocking it, as the pixels might otherwise be uninitialized memory. + * + * Which is to say: locking and immediately unlocking a texture can result in + * corrupted textures, depending on the renderer in use. + * + * \param texture a texture locked by SDL_LockTexture(). + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockTexture + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); + +/** + * Set a texture as the current rendering target. + * + * The default render target is the window for which the renderer was created. + * To stop rendering to a texture and render to the window again, call this + * function with a NULL `texture`. + * + * Viewport, cliprect, scale, and logical presentation are unique to each + * render target. Get and set functions for these states apply to the current + * render target set by this function, and those states persist on each target + * when the current render target changes. + * + * \param renderer the rendering context. + * \param texture the targeted texture, which must be created with the + * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the + * window instead of a texture. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderTarget + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); + +/** + * Get the current render target. + * + * The default render target is the window for which the renderer was created, + * and is reported a NULL here. + * + * \param renderer the rendering context. + * \returns the current render target or NULL for the default render target. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderTarget + */ +extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer); + +/** + * Set a device-independent resolution and presentation mode for rendering. + * + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the current render target is always the + * requested dimensions, scaling to the actual resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. + * + * Logical presentation can be used with both render target textures and the + * renderer's window; the state is unique to each render target, and this + * function sets the state for the current render target. It might be useful + * to draw to a texture that matches the window dimensions with logical + * presentation enabled, and then draw that texture across the entire window + * with logical presentation disabled. Be careful not to render both with + * logical presentation enabled, however, as this could produce + * double-letterboxing, etc. + * + * You can disable logical coordinates by setting the mode to + * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel + * resolution of the render target; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text, for example. + * + * For the renderer's window, letterboxing is drawn into the framebuffer if + * logical presentation is enabled during SDL_RenderPresent; be sure to + * reenable it before presenting if you were toggling it, otherwise the + * letterbox areas might have artifacts from previous frames (or artifacts + * from external overlays, etc). Letterboxing is never drawn into texture + * render targets; be sure to call SDL_RenderClear() before drawing into the + * texture so the letterboxing areas are cleared, if appropriate. + * + * You can convert coordinates in an event into rendering coordinates using + * SDL_ConvertEventToRenderCoordinates(). + * + * \param renderer the rendering context. + * \param w the width of the logical resolution. + * \param h the height of the logical resolution. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ConvertEventToRenderCoordinates + * \sa SDL_GetRenderLogicalPresentation + * \sa SDL_GetRenderLogicalPresentationRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); + +/** + * Get device independent resolution and presentation mode for rendering. + * + * This function gets the width and height of the logical rendering output, or + * the output size in pixels if a logical resolution is not enabled. + * + * Each render target has its own logical presentation state. This function + * gets the state for the current render target. + * + * \param renderer the rendering context. + * \param w an int to be filled with the width. + * \param h an int to be filled with the height. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderLogicalPresentation + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); + +/** + * Get the final presentation rectangle for rendering. + * + * This function returns the calculated rectangle used for logical + * presentation, based on the presentation mode and output size. If logical + * presentation is disabled, it will fill the rectangle with the output size, + * in pixels. + * + * Each render target has its own logical presentation state. This function + * gets the rectangle for the current render target. + * + * \param renderer the rendering context. + * \param rect a pointer filled in with the final presentation rectangle, may + * be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderLogicalPresentation + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); + +/** + * Get a point in render coordinates when given a point in window coordinates. + * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * \param renderer the rendering context. + * \param window_x the x coordinate in window coordinates. + * \param window_y the y coordinate in window coordinates. + * \param x a pointer filled with the x coordinate in render coordinates. + * \param y a pointer filled with the y coordinate in render coordinates. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderLogicalPresentation + * \sa SDL_SetRenderScale + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); + +/** + * Get a point in window coordinates when given a point in render coordinates. + * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * \param renderer the rendering context. + * \param x the x coordinate in render coordinates. + * \param y the y coordinate in render coordinates. + * \param window_x a pointer filled with the x coordinate in window + * coordinates. + * \param window_y a pointer filled with the y coordinate in window + * coordinates. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderLogicalPresentation + * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); + +/** + * Convert the coordinates in an event to render coordinates. + * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * + * Touch coordinates are converted from normalized coordinates in the window + * to non-normalized rendering coordinates. + * + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. + * + * \param renderer the rendering context. + * \param event the event to modify. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderCoordinatesFromWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); + +/** + * Set the drawing area for rendering on the current target. + * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * + * Each render target has its own viewport. This function sets the viewport + * for the current render target. + * + * \param renderer the rendering context. + * \param rect the SDL_Rect structure representing the drawing area, or NULL + * to set the viewport to the entire target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderViewport + * \sa SDL_RenderViewportSet + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); + +/** + * Get the drawing area for the current target. + * + * Each render target has its own viewport. This function gets the viewport + * for the current render target. + * + * \param renderer the rendering context. + * \param rect an SDL_Rect structure filled in with the current drawing area. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderViewportSet + * \sa SDL_SetRenderViewport + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); + +/** + * Return whether an explicit rectangle was set as the viewport. + * + * This is useful if you're saving and restoring the viewport and want to know + * whether you should restore a specific rectangle or NULL. + * + * Each render target has its own viewport. This function checks the viewport + * for the current render target. + * + * \param renderer the rendering context. + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderViewport + * \sa SDL_SetRenderViewport + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); + +/** + * Get the safe area for rendering within the current viewport. + * + * Some devices have portions of the screen which are partially obscured or + * not interactive, possibly due to on-screen controls, curved edges, camera + * notches, TV overscan, etc. This function provides the area of the current + * viewport which is safe to have interactible content. You should continue + * rendering into the rest of the render target, but it should not contain + * visually important or interactible content. + * + * \param renderer the rendering context. + * \param rect a pointer filled in with the area that is safe for interactive + * content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); + +/** + * Set the clip rectangle for rendering on the specified target. + * + * Each render target has its own clip rectangle. This function sets the + * cliprect for the current render target. + * + * \param renderer the rendering context. + * \param rect an SDL_Rect structure representing the clip area, relative to + * the viewport, or NULL to disable clipping. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderClipRect + * \sa SDL_RenderClipEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); + +/** + * Get the clip rectangle for the current target. + * + * Each render target has its own clip rectangle. This function gets the + * cliprect for the current render target. + * + * \param renderer the rendering context. + * \param rect an SDL_Rect structure filled in with the current clipping area + * or an empty rectangle if clipping is disabled. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderClipEnabled + * \sa SDL_SetRenderClipRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); + +/** + * Get whether clipping is enabled on the given render target. + * + * Each render target has its own clip rectangle. This function checks the + * cliprect for the current render target. + * + * \param renderer the rendering context. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderClipRect + * \sa SDL_SetRenderClipRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); + +/** + * Set the drawing scale for rendering on the current target. + * + * The drawing coordinates are scaled by the x/y scaling factors before they + * are used by the renderer. This allows resolution independent drawing with a + * single coordinate system. + * + * If this results in scaling or subpixel drawing by the rendering backend, it + * will be handled using the appropriate quality hints. For best results use + * integer scaling factors. + * + * Each render target has its own scale. This function sets the scale for the + * current render target. + * + * \param renderer the rendering context. + * \param scaleX the horizontal scaling factor. + * \param scaleY the vertical scaling factor. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderScale + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); + +/** + * Get the drawing scale for the current target. + * + * Each render target has its own scale. This function gets the scale for the + * current render target. + * + * \param renderer the rendering context. + * \param scaleX a pointer filled in with the horizontal scaling factor. + * \param scaleY a pointer filled in with the vertical scaling factor. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderScale + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); + +/** + * Set the color used for drawing operations. + * + * Set the color for drawing or filling rectangles, lines, and points, and for + * SDL_RenderClear(). + * + * \param renderer the rendering context. + * \param r the red value used to draw on the rendering target. + * \param g the green value used to draw on the rendering target. + * \param b the blue value used to draw on the rendering target. + * \param a the alpha value used to draw on the rendering target; usually + * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to + * specify how the alpha channel is used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderDrawColor + * \sa SDL_SetRenderDrawColorFloat + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); + +/** + * Set the color used for drawing operations (Rect, Line and Clear). + * + * Set the color for drawing or filling rectangles, lines, and points, and for + * SDL_RenderClear(). + * + * \param renderer the rendering context. + * \param r the red value used to draw on the rendering target. + * \param g the green value used to draw on the rendering target. + * \param b the blue value used to draw on the rendering target. + * \param a the alpha value used to draw on the rendering target. Use + * SDL_SetRenderDrawBlendMode to specify how the alpha channel is + * used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderDrawColorFloat + * \sa SDL_SetRenderDrawColor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); + +/** + * Get the color used for drawing operations (Rect, Line and Clear). + * + * \param renderer the rendering context. + * \param r a pointer filled in with the red value used to draw on the + * rendering target. + * \param g a pointer filled in with the green value used to draw on the + * rendering target. + * \param b a pointer filled in with the blue value used to draw on the + * rendering target. + * \param a a pointer filled in with the alpha value used to draw on the + * rendering target; usually `SDL_ALPHA_OPAQUE` (255). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderDrawColorFloat + * \sa SDL_SetRenderDrawColor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); + +/** + * Get the color used for drawing operations (Rect, Line and Clear). + * + * \param renderer the rendering context. + * \param r a pointer filled in with the red value used to draw on the + * rendering target. + * \param g a pointer filled in with the green value used to draw on the + * rendering target. + * \param b a pointer filled in with the blue value used to draw on the + * rendering target. + * \param a a pointer filled in with the alpha value used to draw on the + * rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderDrawColorFloat + * \sa SDL_GetRenderDrawColor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); + +/** + * Set the color scale used for render operations. + * + * The color scale is an additional scale multiplied into the pixel color + * value while rendering. This can be used to adjust the brightness of colors + * during HDR rendering, or changing HDR video brightness when playing on an + * SDR display. + * + * The color scale does not affect the alpha channel, only the color + * brightness. + * + * \param renderer the rendering context. + * \param scale the color scale value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderColorScale + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); + +/** + * Get the color scale used for render operations. + * + * \param renderer the rendering context. + * \param scale a pointer filled in with the current color scale value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderColorScale + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); + +/** + * Set the blend mode used for drawing operations (Fill and Line). + * + * If the blend mode is not supported, the closest supported mode is chosen. + * + * \param renderer the rendering context. + * \param blendMode the SDL_BlendMode to use for blending. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderDrawBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); + +/** + * Get the blend mode used for drawing operations. + * + * \param renderer the rendering context. + * \param blendMode a pointer filled in with the current SDL_BlendMode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderDrawBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); + +/** + * Clear the current rendering target with the drawing color. + * + * This function clears the entire rendering target, ignoring the viewport and + * the clip rectangle. Note, that clearing will also set/fill all pixels of + * the rendering target to current renderer draw color, so make sure to invoke + * SDL_SetRenderDrawColor() when needed. + * + * \param renderer the rendering context. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderDrawColor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); + +/** + * Draw a point on the current rendering target at subpixel precision. + * + * \param renderer the renderer which should draw a point. + * \param x the x coordinate of the point. + * \param y the y coordinate of the point. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderPoints + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); + +/** + * Draw multiple points on the current rendering target at subpixel precision. + * + * \param renderer the renderer which should draw multiple points. + * \param points the points to draw. + * \param count the number of points to draw. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderPoint + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); + +/** + * Draw a line on the current rendering target at subpixel precision. + * + * \param renderer the renderer which should draw a line. + * \param x1 the x coordinate of the start point. + * \param y1 the y coordinate of the start point. + * \param x2 the x coordinate of the end point. + * \param y2 the y coordinate of the end point. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderLines + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); + +/** + * Draw a series of connected lines on the current rendering target at + * subpixel precision. + * + * \param renderer the renderer which should draw multiple lines. + * \param points the points along the lines. + * \param count the number of points, drawing count-1 lines. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderLine + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); + +/** + * Draw a rectangle on the current rendering target at subpixel precision. + * + * \param renderer the renderer which should draw a rectangle. + * \param rect a pointer to the destination rectangle, or NULL to outline the + * entire rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderRects + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); + +/** + * Draw some number of rectangles on the current rendering target at subpixel + * precision. + * + * \param renderer the renderer which should draw multiple rectangles. + * \param rects a pointer to an array of destination rectangles. + * \param count the number of rectangles. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); + +/** + * Fill a rectangle on the current rendering target with the drawing color at + * subpixel precision. + * + * \param renderer the renderer which should fill a rectangle. + * \param rect a pointer to the destination rectangle, or NULL for the entire + * rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderFillRects + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); + +/** + * Fill some number of rectangles on the current rendering target with the + * drawing color at subpixel precision. + * + * \param renderer the renderer which should fill multiple rectangles. + * \param rects a pointer to an array of destination rectangles. + * \param count the number of rectangles. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderFillRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); + +/** + * Copy a portion of the texture to the current rendering target at subpixel + * precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param dstrect a pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTextureRotated + * \sa SDL_RenderTextureTiled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); + +/** + * Copy a portion of the source texture to the current rendering target, with + * rotation and flipping, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param dstrect a pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \param angle an angle in degrees that indicates the rotation that will be + * applied to dstrect, rotating it in a clockwise direction. + * \param center a pointer to a point indicating the point around which + * dstrect will be rotated (if NULL, rotation will be done + * around dstrect.w/2, dstrect.h/2). + * \param flip an SDL_FlipMode value stating which flipping actions should be + * performed on the texture. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FRect *dstrect, + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); + +/** + * Tile a portion of the texture to the current rendering target at subpixel + * precision. + * + * The pixels in `srcrect` will be repeated as many times as needed to + * completely fill `dstrect`. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param scale the scale used to transform srcrect into the destination + * rectangle, e.g. a 32x32 texture with a scale of 2 would fill + * 64x64 tiles. + * \param dstrect a pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); + +/** + * Perform a scaled copy using the 9-grid algorithm to the current rendering + * target at subpixel precision. + * + * The pixels in the texture are split into a 3x3 grid, using the different + * corner sizes for each corner, and the sides and center making up the + * remaining pixels. The corners are then scaled using `scale` and fit into + * the corners of the destination rectangle. The sides and center are then + * stretched into place to cover the remaining destination rectangle. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect the SDL_Rect structure representing the rectangle to be used + * for the 9-grid, or NULL to use the entire texture. + * \param left_width the width, in pixels, of the left corners in `srcrect`. + * \param right_width the width, in pixels, of the right corners in `srcrect`. + * \param top_height the height, in pixels, of the top corners in `srcrect`. + * \param bottom_height the height, in pixels, of the bottom corners in + * `srcrect`. + * \param scale the scale used to transform the corner of `srcrect` into the + * corner of `dstrect`, or 0.0f for an unscaled copy. + * \param dstrect a pointer to the destination rectangle, or NULL for the + * entire rendering target. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); + +/** + * Render a list of triangles, optionally using a texture and indices into the + * vertex array Color and alpha modulation is done per vertex + * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). + * + * \param renderer the rendering context. + * \param texture (optional) The SDL texture to use. + * \param vertices vertices. + * \param num_vertices number of vertices. + * \param indices (optional) An array of integer indices into the 'vertices' + * array, if NULL all vertices will be rendered in sequential + * order. + * \param num_indices number of indices. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderGeometryRaw + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, + SDL_Texture *texture, + const SDL_Vertex *vertices, int num_vertices, + const int *indices, int num_indices); + +/** + * Render a list of triangles, optionally using a texture and indices into the + * vertex arrays Color and alpha modulation is done per vertex + * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored). + * + * \param renderer the rendering context. + * \param texture (optional) The SDL texture to use. + * \param xy vertex positions. + * \param xy_stride byte size to move from one element to the next element. + * \param color vertex colors (as SDL_FColor). + * \param color_stride byte size to move from one element to the next element. + * \param uv vertex normalized texture coordinates. + * \param uv_stride byte size to move from one element to the next element. + * \param num_vertices number of vertices. + * \param indices (optional) An array of indices into the 'vertices' arrays, + * if NULL all vertices will be rendered in sequential order. + * \param num_indices number of indices. + * \param size_indices index size: 1 (byte), 2 (short), 4 (int). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderGeometry + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, + SDL_Texture *texture, + const float *xy, int xy_stride, + const SDL_FColor *color, int color_stride, + const float *uv, int uv_stride, + int num_vertices, + const void *indices, int num_indices, int size_indices); + +/** + * Read pixels from the current rendering target. + * + * The returned surface contains pixels inside the desired area clipped to the + * current viewport, and should be freed with SDL_DestroySurface(). + * + * Note that this returns the actual pixels on the screen, so if you are using + * logical presentation you should use SDL_GetRenderLogicalPresentationRect() + * to get the area containing your content. + * + * **WARNING**: This is a very slow operation, and should not be used + * frequently. If you're using this on the main rendering target, it should be + * called after rendering and before SDL_RenderPresent(). + * + * \param renderer the rendering context. + * \param rect an SDL_Rect structure representing the area to read, which will + * be clipped to the current viewport, or NULL for the entire + * viewport. + * \returns a new SDL_Surface on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); + +/** + * Update the screen with any rendering performed since the previous call. + * + * SDL's rendering functions operate on a backbuffer; that is, calling a + * rendering function such as SDL_RenderLine() does not directly put a line on + * the screen, but rather updates the backbuffer. As such, you compose your + * entire scene and *present* the composed backbuffer to the screen as a + * complete picture. + * + * Therefore, when using SDL's rendering API, one does all drawing intended + * for the frame, and then calls this function once per frame to present the + * final drawing to the user. + * + * The backbuffer should be considered invalidated after each present; do not + * assume that previous contents will exist between frames. You are strongly + * encouraged to call SDL_RenderClear() to initialize the backbuffer before + * starting each new frame's drawing, even if you plan to overwrite every + * pixel. + * + * Please note, that in case of rendering to a texture - there is **no need** + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. + * + * \param renderer the rendering context. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRenderer + * \sa SDL_RenderClear + * \sa SDL_RenderFillRect + * \sa SDL_RenderFillRects + * \sa SDL_RenderLine + * \sa SDL_RenderLines + * \sa SDL_RenderPoint + * \sa SDL_RenderPoints + * \sa SDL_RenderRect + * \sa SDL_RenderRects + * \sa SDL_SetRenderDrawBlendMode + * \sa SDL_SetRenderDrawColor + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); + +/** + * Destroy the specified texture. + * + * Passing NULL or an otherwise invalid texture will set the SDL error message + * to "Invalid texture". + * + * \param texture the texture to destroy. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); + +/** + * Destroy the rendering context for a window and free all associated + * textures. + * + * This should be called before destroying the associated window. + * + * \param renderer the rendering context. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRenderer + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); + +/** + * Force the rendering context to flush any pending commands and state. + * + * You do not need to (and in fact, shouldn't) call this function unless you + * are planning to call into OpenGL/Direct3D/Metal/whatever directly, in + * addition to using an SDL_Renderer. + * + * This is for a very-specific case: if you are using SDL's render API, and + * you plan to make OpenGL/D3D/whatever calls in addition to SDL render API + * calls. If this applies, you should call this function between calls to + * SDL's render API and the low-level API you're using in cooperation. + * + * In all other cases, you can ignore this function. + * + * This call makes SDL flush any pending rendering work it was queueing up to + * do later in a single batch, and marks any internal cached state as invalid, + * so it'll prepare all its state again later, from scratch. + * + * This means you do not need to save state in your rendering code to protect + * the SDL renderer. However, there lots of arbitrary pieces of Direct3D and + * OpenGL state that can confuse things; you should use your best judgment and + * be prepared to make changes if specific state needs to be protected. + * + * \param renderer the rendering context. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); + +/** + * Get the CAMetalLayer associated with the given Metal renderer. + * + * This function returns `void *`, so SDL doesn't have to include Metal's + * headers, but it can be safely cast to a `CAMetalLayer *`. + * + * \param renderer the renderer to query. + * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a + * Metal renderer. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderMetalCommandEncoder + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer); + +/** + * Get the Metal command encoder for the current frame. + * + * This function returns `void *`, so SDL doesn't have to include Metal's + * headers, but it can be safely cast to an `id`. + * + * This will return NULL if Metal refuses to give SDL a drawable to render to, + * which might happen if the window is hidden/minimized/offscreen. This + * doesn't apply to command encoders for render targets, just the window's + * backbuffer. Check your return values! + * + * \param renderer the renderer to query. + * \returns an `id` on success, or NULL if the + * renderer isn't a Metal renderer or there was an error. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderMetalLayer + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer *renderer); + + +/** + * Add a set of synchronization semaphores for the current frame. + * + * The Vulkan renderer will wait for `wait_semaphore` before submitting + * rendering commands and signal `signal_semaphore` after rendering commands + * are complete for this frame. + * + * This should be called each frame that you want semaphore synchronization. + * The Vulkan renderer may have multiple frames in flight on the GPU, so you + * should have multiple semaphores that are used for synchronization. Querying + * SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER will give you the + * maximum number of semaphores you'll need. + * + * \param renderer the rendering context. + * \param wait_stage_mask the VkPipelineStageFlags for the wait. + * \param wait_semaphore a VkSempahore to wait on before rendering the current + * frame, or 0 if not needed. + * \param signal_semaphore a VkSempahore that SDL will signal when rendering + * for the current frame is complete, or 0 if not + * needed. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is **NOT** safe to call this function from two threads at + * once. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); + +/** + * Toggle VSync of the given renderer. + * + * When a renderer is created, vsync defaults to SDL_RENDERER_VSYNC_DISABLED. + * + * The `vsync` parameter can be 1 to synchronize present with every vertical + * refresh, 2 to synchronize present with every second vertical refresh, etc., + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. + * + * \param renderer the renderer to toggle. + * \param vsync the vertical refresh sync interval. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderVSync + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); + +#define SDL_RENDERER_VSYNC_DISABLED 0 +#define SDL_RENDERER_VSYNC_ADAPTIVE (-1) + +/** + * Get VSync of the given renderer. + * + * \param renderer the renderer to toggle. + * \param vsync an int filled with the current vertical refresh sync interval. + * See SDL_SetRenderVSync() for the meaning of the value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetRenderVSync + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_render_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_revision.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_revision.h new file mode 100644 index 0000000000..d9281053e8 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_revision.h @@ -0,0 +1,56 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* WIKI CATEGORY: Version */ + +/* + * SDL_revision.h contains the SDL revision, which might be defined on the + * compiler command line, or generated right into the header itself by the + * build system. + */ + +#ifndef SDL_revision_h_ +#define SDL_revision_h_ + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * This macro is a string describing the source at a particular point in + * development. + * + * This string is often generated from revision control's state at build time. + * + * This string can be quite complex and does not follow any standard. For + * example, it might be something like "SDL-prerelease-3.1.1-47-gf687e0732". + * It might also be user-defined at build time, so it's best to treat it as a + * clue in debugging forensics and not something the app will parse in any + * way. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_REVISION "Some arbitrary string decided at SDL build time" +#elif defined(SDL_VENDOR_INFO) +#define SDL_REVISION "release-3.2.18-0-g68bfcb6c5 (" SDL_VENDOR_INFO ")" +#else +#define SDL_REVISION "release-3.2.18-0-g68bfcb6c5" +#endif + +#endif /* SDL_revision_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_scancode.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_scancode.h similarity index 85% rename from code/thirdparty/SDL2-2.32.8/include/SDL_scancode.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_scancode.h index 0652d7ef66..9650a6cfe3 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_scancode.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_scancode.h @@ -23,22 +23,31 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ #define SDL_scancode_h_ -#include "SDL_stdinc.h" +#include /** * The SDL keyboard scancode representation. * + * An SDL scancode is the physical representation of a key on the keyboard, + * independent of language and keyboard mapping. + * * Values of this type are used to represent keyboard keys, among other places - * in the SDL_Keysym::scancode key.keysym.scancode field of the SDL_Event - * structure. + * in the `scancode` field of the SDL_KeyboardEvent structure. * * The values in this enumeration are based on the USB usage page standard: - * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf + * https://usb.org/sites/default/files/hut1_5.pdf + * + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -336,7 +345,7 @@ typedef enum SDL_Scancode SDL_SCANCODE_MODE = 257, /**< I'm not sure if this is really not covered * by any of the above, but since there's a - * special KMOD_MODE for it I'm adding it here + * special SDL_KMOD_MODE for it I'm adding it here */ /* @} *//* Usage page 0x07 */ @@ -345,7 +354,6 @@ typedef enum SDL_Scancode * \name Usage page 0x0C * * These values are mapped from usage page 0x0C (USB consumer page). - * See https://usb.org/sites/default/files/hut1_2.pdf * * There are way more keys in the spec than we can represent in the * current scancode range, so pick the ones that commonly come up in @@ -353,59 +361,42 @@ typedef enum SDL_Scancode */ /* @{ */ - SDL_SCANCODE_AUDIONEXT = 258, - SDL_SCANCODE_AUDIOPREV = 259, - SDL_SCANCODE_AUDIOSTOP = 260, - SDL_SCANCODE_AUDIOPLAY = 261, - SDL_SCANCODE_AUDIOMUTE = 262, - SDL_SCANCODE_MEDIASELECT = 263, - SDL_SCANCODE_WWW = 264, /**< AL Internet Browser */ - SDL_SCANCODE_MAIL = 265, - SDL_SCANCODE_CALCULATOR = 266, /**< AL Calculator */ - SDL_SCANCODE_COMPUTER = 267, - SDL_SCANCODE_AC_SEARCH = 268, /**< AC Search */ - SDL_SCANCODE_AC_HOME = 269, /**< AC Home */ - SDL_SCANCODE_AC_BACK = 270, /**< AC Back */ - SDL_SCANCODE_AC_FORWARD = 271, /**< AC Forward */ - SDL_SCANCODE_AC_STOP = 272, /**< AC Stop */ - SDL_SCANCODE_AC_REFRESH = 273, /**< AC Refresh */ - SDL_SCANCODE_AC_BOOKMARKS = 274, /**< AC Bookmarks */ + SDL_SCANCODE_SLEEP = 258, /**< Sleep */ + SDL_SCANCODE_WAKE = 259, /**< Wake */ + + SDL_SCANCODE_CHANNEL_INCREMENT = 260, /**< Channel Increment */ + SDL_SCANCODE_CHANNEL_DECREMENT = 261, /**< Channel Decrement */ + + SDL_SCANCODE_MEDIA_PLAY = 262, /**< Play */ + SDL_SCANCODE_MEDIA_PAUSE = 263, /**< Pause */ + SDL_SCANCODE_MEDIA_RECORD = 264, /**< Record */ + SDL_SCANCODE_MEDIA_FAST_FORWARD = 265, /**< Fast Forward */ + SDL_SCANCODE_MEDIA_REWIND = 266, /**< Rewind */ + SDL_SCANCODE_MEDIA_NEXT_TRACK = 267, /**< Next Track */ + SDL_SCANCODE_MEDIA_PREVIOUS_TRACK = 268, /**< Previous Track */ + SDL_SCANCODE_MEDIA_STOP = 269, /**< Stop */ + SDL_SCANCODE_MEDIA_EJECT = 270, /**< Eject */ + SDL_SCANCODE_MEDIA_PLAY_PAUSE = 271, /**< Play / Pause */ + SDL_SCANCODE_MEDIA_SELECT = 272, /* Media Select */ + + SDL_SCANCODE_AC_NEW = 273, /**< AC New */ + SDL_SCANCODE_AC_OPEN = 274, /**< AC Open */ + SDL_SCANCODE_AC_CLOSE = 275, /**< AC Close */ + SDL_SCANCODE_AC_EXIT = 276, /**< AC Exit */ + SDL_SCANCODE_AC_SAVE = 277, /**< AC Save */ + SDL_SCANCODE_AC_PRINT = 278, /**< AC Print */ + SDL_SCANCODE_AC_PROPERTIES = 279, /**< AC Properties */ + + SDL_SCANCODE_AC_SEARCH = 280, /**< AC Search */ + SDL_SCANCODE_AC_HOME = 281, /**< AC Home */ + SDL_SCANCODE_AC_BACK = 282, /**< AC Back */ + SDL_SCANCODE_AC_FORWARD = 283, /**< AC Forward */ + SDL_SCANCODE_AC_STOP = 284, /**< AC Stop */ + SDL_SCANCODE_AC_REFRESH = 285, /**< AC Refresh */ + SDL_SCANCODE_AC_BOOKMARKS = 286, /**< AC Bookmarks */ /* @} *//* Usage page 0x0C */ - /** - * \name Walther keys - * - * These are values that Christian Walther added (for mac keyboard?). - */ - /* @{ */ - - SDL_SCANCODE_BRIGHTNESSDOWN = 275, - SDL_SCANCODE_BRIGHTNESSUP = 276, - SDL_SCANCODE_DISPLAYSWITCH = 277, /**< display mirroring/dual display - switch, video mode switch */ - SDL_SCANCODE_KBDILLUMTOGGLE = 278, - SDL_SCANCODE_KBDILLUMDOWN = 279, - SDL_SCANCODE_KBDILLUMUP = 280, - SDL_SCANCODE_EJECT = 281, - SDL_SCANCODE_SLEEP = 282, /**< SC System Sleep */ - - SDL_SCANCODE_APP1 = 283, - SDL_SCANCODE_APP2 = 284, - - /* @} *//* Walther keys */ - - /** - * \name Usage page 0x0C (additional media keys) - * - * These values are mapped from usage page 0x0C (USB consumer page). - */ - /* @{ */ - - SDL_SCANCODE_AUDIOREWIND = 285, - SDL_SCANCODE_AUDIOFASTFORWARD = 286, - - /* @} *//* Usage page 0x0C (additional media keys) */ /** * \name Mobile keys @@ -429,10 +420,10 @@ typedef enum SDL_Scancode /* Add any other keys here. */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ + + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_sensor.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_sensor.h similarity index 50% rename from code/thirdparty/SDL2-2.32.8/include/SDL_sensor.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_sensor.h index d4b1c511d7..b220f0538c 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_sensor.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_sensor.h @@ -22,16 +22,23 @@ /** * # CategorySensor * - * Include file for SDL sensor event handling + * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ #define SDL_sensor_h_ -#include "SDL_stdinc.h" -#include "SDL_error.h" +#include +#include +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus /* *INDENT-OFF* */ @@ -40,24 +47,33 @@ extern "C" { #endif /** - * \brief SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct _SDL_Sensor; -typedef struct _SDL_Sensor SDL_Sensor; +typedef struct SDL_Sensor SDL_Sensor; /** * This is a unique ID for a sensor for the time it is connected to the * system, and is never reused for the lifetime of the application. * - * The ID value starts at 0 and increments from there. The value -1 is an - * invalid ID. + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. */ -typedef Sint32 SDL_SensorID; +typedef Uint32 SDL_SensorID; + +/** + * A constant to represent standard gravity for accelerometer sensors. + * + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_STANDARD_GRAVITY 9.80665f /** * The different sensors defined by SDL. @@ -109,7 +125,9 @@ typedef Sint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \sa SDL_GetDisplayOrientation + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentDisplayOrientation */ typedef enum SDL_SensorType { @@ -123,184 +141,159 @@ typedef enum SDL_SensorType SDL_SENSOR_GYRO_R /**< Gyroscope for right Joy-Con controller */ } SDL_SensorType; -/** - * A constant to represent standard gravity for accelerometer sensors. - * - * The accelerometer returns the current acceleration in SI meters per second - * squared. This measurement includes the force of gravity, so a device at - * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the - * earth, which is a positive Y value. - */ -#define SDL_STANDARD_GRAVITY 9.80665f /* Function prototypes */ /** - * Locking for multi-threaded access to the sensor API - * - * If you are using the sensor API or handling events from multiple threads - * you should use these locking functions to protect access to the sensors. - * - * In particular, you are guaranteed that the sensor list won't change, so the - * API functions that take a sensor index will be valid, and sensor events - * will not be delivered. - * - * \since This function is available since SDL 2.0.14. - */ -extern DECLSPEC void SDLCALL SDL_LockSensors(void); -extern DECLSPEC void SDLCALL SDL_UnlockSensors(void); - -/** - * Count the number of sensors attached to the system right now. + * Get a list of currently connected sensors. * - * \returns the number of sensors detected. + * \param count a pointer filled in with the number of sensors returned, may + * be NULL. + * \returns a 0 terminated array of sensor instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_NumSensors(void); +extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); /** * Get the implementation dependent name of a sensor. * - * \param device_index The sensor to obtain name from. - * \returns the sensor name, or NULL if `device_index` is out of range. + * This can be called before any sensors are opened. + * + * \param instance_id the sensor instance ID. + * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); /** * Get the type of a sensor. * - * \param device_index The sensor to get the type from. - * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is - * out of range. + * This can be called before any sensors are opened. * - * \since This function is available since SDL 2.0.9. + * \param instance_id the sensor instance ID. + * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is + * not valid. + * + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index); +extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); /** * Get the platform dependent type of a sensor. * - * \param device_index The sensor to check. - * \returns the sensor platform dependent type, or -1 if `device_index` is out - * of range. + * This can be called before any sensors are opened. + * + * \param instance_id the sensor instance ID. + * \returns the sensor platform dependent type, or -1 if `instance_id` is not + * valid. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index); +extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); /** - * Get the instance ID of a sensor. + * Open a sensor for use. * - * \param device_index The sensor to get instance id from. - * \returns the sensor instance ID, or -1 if `device_index` is out of range. + * \param instance_id the sensor instance ID. + * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index); +extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); /** - * Open a sensor for use. + * Return the SDL_Sensor associated with an instance ID. * - * \param device_index The sensor to open. - * \returns an SDL_Sensor sensor object, or NULL if an error occurred. + * \param instance_id the sensor instance ID. + * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index); +extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); /** - * Return the SDL_Sensor associated with an instance id. + * Get the properties associated with a sensor. * - * \param instance_id The sensor from instance id. - * \returns an SDL_Sensor object. + * \param sensor the SDL_Sensor object. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id); +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); /** - * Get the implementation dependent name of a sensor + * Get the implementation dependent name of a sensor. * - * \param sensor The SDL_Sensor object. - * \returns the sensor name, or NULL if `sensor` is NULL. + * \param sensor the SDL_Sensor object. + * \returns the sensor name or NULL on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); /** * Get the type of a sensor. * - * \param sensor The SDL_Sensor object to inspect. + * \param sensor the SDL_Sensor object to inspect. * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor); +extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); /** * Get the platform dependent type of a sensor. * - * \param sensor The SDL_Sensor object to inspect. + * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor); +extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); /** * Get the instance ID of a sensor. * - * \param sensor The SDL_Sensor object to inspect. - * \returns the sensor instance ID, or -1 if `sensor` is NULL. + * \param sensor the SDL_Sensor object to inspect. + * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor); +extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); /** * Get the current state of an opened sensor. * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The SDL_Sensor object to query. - * \param data A pointer filled with the current sensor state. - * \param num_values The number of values to write to data. - * \returns 0 or -1 if an error occurred. + * \param sensor the SDL_Sensor object to query. + * \param data a pointer filled with the current sensor state. + * \param num_values the number of values to write to data. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** - * Get the current state of an opened sensor with the timestamp of the last - * update. + * Close a sensor previously opened with SDL_OpenSensor(). * - * The number of values and interpretation of the data is sensor dependent. - * - * \param sensor The SDL_Sensor object to query. - * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not. - * \param data A pointer filled with the current sensor state. - * \param num_values The number of values to write to data. - * \returns 0 or -1 if an error occurred. + * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 2.26.0. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_SensorGetDataWithTimestamp(SDL_Sensor *sensor, Uint64 *timestamp, float *data, int num_values); - -/** - * Close a sensor previously opened with SDL_SensorOpen(). - * - * \param sensor The SDL_Sensor object to close. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor *sensor); +extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); /** * Update the current state of the open sensors. @@ -311,9 +304,9 @@ extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 2.0.9. + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC void SDLCALL SDL_SensorUpdate(void); +extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); /* Ends C function definitions when using C++ */ @@ -322,8 +315,6 @@ extern DECLSPEC void SDLCALL SDL_SensorUpdate(void); } /* *INDENT-ON* */ #endif -#include "close_code.h" +#include #endif /* SDL_sensor_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_stdinc.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_stdinc.h new file mode 100644 index 0000000000..7df253fece --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_stdinc.h @@ -0,0 +1,6137 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryStdinc + * + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). + */ + +#ifndef SDL_stdinc_h_ +#define SDL_stdinc_h_ + +#include + +#include +#include +#include +#include + +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + +#ifndef SDL_DISABLE_ALLOCA +# ifndef alloca +# ifdef HAVE_ALLOCA_H +# include +# elif defined(SDL_PLATFORM_NETBSD) +# if defined(__STRICT_ANSI__) +# define SDL_DISABLE_ALLOCA +# else +# include +# endif +# elif defined(__GNUC__) +# define alloca __builtin_alloca +# elif defined(_MSC_VER) +# include +# define alloca _alloca +# elif defined(__WATCOMC__) +# include +# elif defined(__BORLANDC__) +# include +# elif defined(__DMC__) +# include +# elif defined(SDL_PLATFORM_AIX) +# pragma alloca +# elif defined(__MRC__) +void *alloca(unsigned); +# else +void *alloca(size_t); +# endif +# endif +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) +# define SDL_SIZE_MAX SIZE_MAX +#else +# define SDL_SIZE_MAX ((size_t) -1) +#endif + +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert + */ +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] +#endif + +/** + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. + * + * This macro looks like it double-evaluates the argument, but it does so + * inside of `sizeof`, so there are no side-effects here, as expressions do + * not actually run any code in these cases. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) + +/** + * Macro useful for building other macros with strings in them. + * + * For example: + * + * ```c + * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` + * ``` + * + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_STRINGIFY_ARG(arg) #arg + +/** + * \name Cast operators + * + * Use proper C++ casts when compiled as C++ to be compatible with the option + * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). + */ +/* @{ */ + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) +#define SDL_static_cast(type, expression) static_cast(expression) +#define SDL_const_cast(type, expression) const_cast(expression) +#else +#define SDL_reinterpret_cast(type, expression) ((type)(expression)) +#define SDL_static_cast(type, expression) ((type)(expression)) +#define SDL_const_cast(type, expression) ((type)(expression)) +#endif + +/* @} *//* Cast operators */ + +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FOURCC(A, B, C, D) \ + ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (C))) << 16) | \ + (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (D))) << 24)) + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Append the 64 bit integer suffix to a signed integer literal. + * + * This helps compilers that might believe a integer literal larger than + * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` + * instead of `0xFFFFFFFF1` by itself. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_UINT64_C + */ +#define SDL_SINT64_C(c) c ## LL /* or whatever the current compiler uses. */ + +/** + * Append the 64 bit integer suffix to an unsigned integer literal. + * + * This helps compilers that might believe a integer literal larger than + * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` + * instead of `0xFFFFFFFF1` by itself. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SINT64_C + */ +#define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ + +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) +#define SDL_SINT64_C(c) INT64_C(c) +#elif defined(_MSC_VER) +#define SDL_SINT64_C(c) c ## i64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_SINT64_C(c) c ## L +#else +#define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else +#define SDL_UINT64_C(c) c ## ULL +#endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +/** + * \name Basic data types + */ +/* @{ */ + +/** + * A signed 8-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef int8_t Sint8; +#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ +#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ + +/** + * An unsigned 8-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef uint8_t Uint8; +#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ +#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ + +/** + * A signed 16-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef int16_t Sint16; +#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ +#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ + +/** + * An unsigned 16-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef uint16_t Uint16; +#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ +#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ + +/** + * A signed 32-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef int32_t Sint32; +#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ +#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ + +/** + * An unsigned 32-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +typedef uint32_t Uint32; +#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ +#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ + +/** + * A signed 64-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SINT64_C + */ +typedef int64_t Sint64; +#define SDL_MAX_SINT64 SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* 9223372036854775807 */ +#define SDL_MIN_SINT64 ~SDL_SINT64_C(0x7FFFFFFFFFFFFFFF) /* -9223372036854775808 */ + +/** + * An unsigned 64-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_UINT64_C + */ +typedef uint64_t Uint64; +#define SDL_MAX_UINT64 SDL_UINT64_C(0xFFFFFFFFFFFFFFFF) /* 18446744073709551615 */ +#define SDL_MIN_UINT64 SDL_UINT64_C(0x0000000000000000) /* 0 */ + +/** + * SDL times are signed, 64-bit integers representing nanoseconds since the + * Unix epoch (Jan 1, 1970). + * + * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() + * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with + * SDL_TimeToWindows() and SDL_TimeFromWindows(). + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MAX_SINT64 + * \sa SDL_MIN_SINT64 + */ +typedef Sint64 SDL_Time; +#define SDL_MAX_TIME SDL_MAX_SINT64 +#define SDL_MIN_TIME SDL_MIN_SINT64 + +/* @} *//* Basic data types */ + +/** + * \name Floating-point constants + */ +/* @{ */ + +#ifdef FLT_EPSILON +#define SDL_FLT_EPSILON FLT_EPSILON +#else + +/** + * Epsilon constant, used for comparing floating-point numbers. + * + * Equals by default to platform-defined `FLT_EPSILON`, or + * `1.1920928955078125e-07F` if that's not available. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ +#endif + +/* @} *//* Floating-point constants */ + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + +/* Make sure we have macros for printing width-based integers. + * should define these but this is not true all platforms. + * (for example win32) */ +#ifndef SDL_PRIs64 +#if defined(SDL_PLATFORM_WINDOWS) +#define SDL_PRIs64 "I64d" +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) +#define SDL_PRIs64 "ld" +#else +#define SDL_PRIs64 "lld" +#endif +#endif +#ifndef SDL_PRIu64 +#if defined(SDL_PLATFORM_WINDOWS) +#define SDL_PRIu64 "I64u" +#elif defined(PRIu64) +#define SDL_PRIu64 PRIu64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) +#define SDL_PRIu64 "lu" +#else +#define SDL_PRIu64 "llu" +#endif +#endif +#ifndef SDL_PRIx64 +#if defined(SDL_PLATFORM_WINDOWS) +#define SDL_PRIx64 "I64x" +#elif defined(PRIx64) +#define SDL_PRIx64 PRIx64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#define SDL_PRIx64 "lx" +#else +#define SDL_PRIx64 "llx" +#endif +#endif +#ifndef SDL_PRIX64 +#if defined(SDL_PLATFORM_WINDOWS) +#define SDL_PRIX64 "I64X" +#elif defined(PRIX64) +#define SDL_PRIX64 PRIX64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#define SDL_PRIX64 "lX" +#else +#define SDL_PRIX64 "llX" +#endif +#endif +#ifndef SDL_PRIs32 +#ifdef PRId32 +#define SDL_PRIs32 PRId32 +#else +#define SDL_PRIs32 "d" +#endif +#endif +#ifndef SDL_PRIu32 +#ifdef PRIu32 +#define SDL_PRIu32 PRIu32 +#else +#define SDL_PRIu32 "u" +#endif +#endif +#ifndef SDL_PRIx32 +#ifdef PRIx32 +#define SDL_PRIx32 PRIx32 +#else +#define SDL_PRIx32 "x" +#endif +#endif +#ifndef SDL_PRIX32 +#ifdef PRIX32 +#define SDL_PRIX32 PRIX32 +#else +#define SDL_PRIX32 "X" +#endif +#endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif + +/* Annotations to help code analysis tools */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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) +#define SDL_OUT_CAP(x) +#define SDL_OUT_BYTECAP(x) +#define SDL_OUT_Z_BYTECAP(x) +#define SDL_PRINTF_FORMAT_STRING +#define SDL_SCANF_FORMAT_STRING +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) +#else +#if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ +#include + +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) +#define SDL_OUT_CAP(x) _Out_cap_(x) +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ +#else +#define SDL_IN_BYTECAP(x) +#define SDL_INOUT_Z_CAP(x) +#define SDL_OUT_Z_CAP(x) +#define SDL_OUT_CAP(x) +#define SDL_OUT_BYTECAP(x) +#define SDL_OUT_Z_BYTECAP(x) +#define SDL_PRINTF_FORMAT_STRING +#define SDL_SCANF_FORMAT_STRING +#endif +#if defined(__GNUC__) || defined(__clang__) +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ +#else +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) +#endif +#endif /* SDL_DISABLE_ANALYZE_MACROS */ + +/** \cond */ +#ifndef DOXYGEN_SHOULD_IGNORE_THIS +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); +#endif /* DOXYGEN_SHOULD_IGNORE_THIS */ +/** \endcond */ + +/* Check to make sure enums are the size of ints, for structure packing. + For both Watcom C/C++ and Borland C/C++ the compiler option that makes + enums having the size of an int must be enabled. + This is "-b" for Borland C/C++ and "-ei" for Watcom C/C++ (v11). +*/ + +/** \cond */ +#ifndef DOXYGEN_SHOULD_IGNORE_THIS +#if !defined(SDL_PLATFORM_VITA) && !defined(SDL_PLATFORM_3DS) +/* TODO: include/SDL_stdinc.h:390: error: size of array 'SDL_dummy_enum' is negative */ +typedef enum SDL_DUMMY_ENUM +{ + DUMMY_ENUM_VALUE +} SDL_DUMMY_ENUM; + +SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); +#endif +#endif /* DOXYGEN_SHOULD_IGNORE_THIS */ +/** \endcond */ + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) +#define SDL_stack_free(data) +#else +#define SDL_stack_alloc(type, count) (type*)SDL_malloc(sizeof(type)*(count)) +#define SDL_stack_free(data) SDL_free(data) +#endif + +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If the allocation is successful, the returned pointer is guaranteed to be + * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in + * C11 and later) or `2 * sizeof(void *)`, whichever is smaller. Use + * SDL_aligned_alloc() if you need to allocate memory aligned to an alignment + * greater than this guarantee. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ +extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * If the allocation is successful, the returned pointer is guaranteed to be + * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in + * C11 and later) or `2 * sizeof(void *)`, whichever is smaller. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ +extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * If the allocation is successfully resized, the returned pointer is + * guaranteed to be aligned to either the *fundamental alignment* + * (`alignof(max_align_t)` in C11 and later) or `2 * sizeof(void *)`, + * whichever is smaller. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ +extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ +extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); + +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ +typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ +typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ +typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ +typedef void (SDLCALL *SDL_free_func)(void *mem); + +/** + * Get the original set of SDL memory functions. + * + * This is what SDL_malloc and friends will use by default, if there has been + * no call to SDL_SetMemoryFunctions. This is not necessarily using the C + * runtime's `malloc` functions behind the scenes! Different platforms and + * build configurations might do any number of unexpected things. + * + * \param malloc_func filled with malloc function. + * \param calloc_func filled with calloc function. + * \param realloc_func filled with realloc function. + * \param free_func filled with free function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, + SDL_calloc_func *calloc_func, + SDL_realloc_func *realloc_func, + SDL_free_func *free_func); + +/** + * Get the current set of SDL memory functions. + * + * \param malloc_func filled with malloc function. + * \param calloc_func filled with calloc function. + * \param realloc_func filled with realloc function. + * \param free_func filled with free function. + * + * \threadsafety This does not hold a lock, so do not call this in the + * unlikely event of a background thread calling + * SDL_SetMemoryFunctions simultaneously. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetMemoryFunctions + * \sa SDL_GetOriginalMemoryFunctions + */ +extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, + SDL_calloc_func *calloc_func, + SDL_realloc_func *realloc_func, + SDL_free_func *free_func); + +/** + * Replace SDL's memory allocation functions with a custom set. + * + * It is not safe to call this function once any allocations have been made, + * as future calls to SDL_free will use the new allocator, even if they came + * from an SDL_malloc made with the old one! + * + * If used, usually this needs to be the first call made into the SDL library, + * if not the very first thing done at program startup time. + * + * \param malloc_func custom malloc function. + * \param calloc_func custom calloc function. + * \param realloc_func custom realloc function. + * \param free_func custom free function. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but one + * should not replace the memory functions once any allocations + * are made! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMemoryFunctions + * \sa SDL_GetOriginalMemoryFunctions + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, + SDL_calloc_func calloc_func, + SDL_realloc_func realloc_func, + SDL_free_func free_func); + +/** + * Allocate memory aligned to a specific alignment. + * + * The memory returned by this function must be freed with SDL_aligned_free(), + * _not_ SDL_free(). + * + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. + * \param size the size to allocate. + * \returns a pointer to the aligned memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_aligned_free + */ +extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment, size_t size); + +/** + * Free memory allocated by SDL_aligned_alloc(). + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_aligned_alloc + */ +extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); + +/** + * Get the number of outstanding (unfreed) allocations. + * + * \returns the number of allocations or -1 if allocation counting is + * disabled. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); + +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; + +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ +typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ +extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ +extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ +typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ +extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ +extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); + +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) + +/** + * Query if a character is alphabetic (a letter). + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * for English 'a-z' and 'A-Z' as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); + +/** + * Query if a character is alphabetic (a letter) or a number. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * for English 'a-z', 'A-Z', and '0-9' as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); + +/** + * Report if a character is blank (a space or tab). + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * 0x20 (space) or 0x9 (tab) as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); + +/** + * Report if a character is a control character. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * 0 through 0x1F, and 0x7F, as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); + +/** + * Report if a character is a numeric digit. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * '0' (0x30) through '9' (0x39), as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); + +/** + * Report if a character is a hexadecimal digit. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * 'A' through 'F', 'a' through 'f', and '0' through '9', as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); + +/** + * Report if a character is a punctuation mark. + * + * **WARNING**: Regardless of system locale, this is equivalent to + * `((SDL_isgraph(x)) && (!SDL_isalnum(x)))`. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isgraph + * \sa SDL_isalnum + */ +extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); + +/** + * Report if a character is whitespace. + * + * **WARNING**: Regardless of system locale, this will only treat the + * following ASCII values as true: + * + * - space (0x20) + * - tab (0x09) + * - newline (0x0A) + * - vertical tab (0x0B) + * - form feed (0x0C) + * - return (0x0D) + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); + +/** + * Report if a character is upper case. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * 'A' through 'Z' as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); + +/** + * Report if a character is lower case. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * 'a' through 'z' as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); + +/** + * Report if a character is "printable". + * + * Be advised that "printable" has a definition that goes back to text + * terminals from the dawn of computing, making this a sort of special case + * function that is not suitable for Unicode (or most any) text management. + * + * **WARNING**: Regardless of system locale, this will only treat ASCII values + * ' ' (0x20) through '~' (0x7E) as true. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); + +/** + * Report if a character is any "printable" except space. + * + * Be advised that "printable" has a definition that goes back to text + * terminals from the dawn of computing, making this a sort of special case + * function that is not suitable for Unicode (or most any) text management. + * + * **WARNING**: Regardless of system locale, this is equivalent to + * `(SDL_isprint(x)) && ((x) != ' ')`. + * + * \param x character value to check. + * \returns non-zero if x falls within the character class, zero otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isprint + */ +extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); + +/** + * Convert low-ASCII English letters to uppercase. + * + * **WARNING**: Regardless of system locale, this will only convert ASCII + * values 'a' through 'z' to uppercase. + * + * This function returns the uppercase equivalent of `x`. If a character + * cannot be converted, or is already uppercase, this function returns `x`. + * + * \param x character value to check. + * \returns capitalized version of x, or x if no conversion available. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); + +/** + * Convert low-ASCII English letters to lowercase. + * + * **WARNING**: Regardless of system locale, this will only convert ASCII + * values 'A' through 'Z' to lowercase. + * + * This function returns the lowercase equivalent of `x`. If a character + * cannot be converted, or is already lowercase, this function returns `x`. + * + * \param x character value to check. + * \returns lowercase version of x, or x if no conversion available. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); + +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); + +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ +extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + +/* Take advantage of compiler optimizations for memcpy */ +#ifndef SDL_SLOW_MEMCPY +#ifdef SDL_memcpy +#undef SDL_memcpy +#endif +#define SDL_memcpy memcpy +#endif + + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +#define SDL_copyp(dst, src) \ + { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ + SDL_memcpy((dst), (src), sizeof(*(src))) + +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ +extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + +/* Take advantage of compiler optimizations for memmove */ +#ifndef SDL_SLOW_MEMMOVE +#ifdef SDL_memmove +#undef SDL_memmove +#endif +#define SDL_memmove memmove +#endif + +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); + +/* Take advantage of compiler optimizations for memset */ +#ifndef SDL_SLOW_MEMSET +#ifdef SDL_memset +#undef SDL_memset +#endif +#define SDL_memset memset +#endif + +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ +#define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ +#define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ +#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.2.0. + */ +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.2.0. + * + * \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.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \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 + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \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 + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); + +/** + * Compare two null-terminated wide strings. + * + * This only compares wchar_t values until it hits a null-terminating + * character; it does not care if the string is well-formed UTF-16 (or UTF-32, + * depending on your platform's wchar_t size), or uses valid Unicode values. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); + +/** + * Compare two wide strings up to a number of wchar_t values. + * + * This only compares wchar_t values; it does not care if the string is + * well-formed UTF-16 (or UTF-32, depending on your platform's wchar_t size), + * or uses valid Unicode values. + * + * Note that while this function is intended to be used with UTF-16 (or + * UTF-32, depending on your platform's definition of wchar_t), it is + * comparing raw wchar_t values and not Unicode codepoints: `maxlen` specifies + * a wchar_t limit! If the limit lands in the middle of a multi-wchar UTF-16 + * sequence, it will only compare a portion of the final character. + * + * `maxlen` specifies a maximum number of wchar_t to compare; if the strings + * match to this number of wide chars (or both have matched to a + * null-terminator character before this count), they will be considered + * equal. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \param maxlen the maximum number of wchar_t to compare. + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); + +/** + * Compare two null-terminated wide strings, case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be + * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this + * handles Unicode, it expects the string to be well-formed and not a + * null-terminated string of arbitrary bytes. Characters that are not valid + * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); + +/** + * Compare two wide strings, case-insensitively, up to a number of wchar_t. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Depending on your platform, "wchar_t" might be 2 bytes, and expected to be + * UTF-16 encoded (like Windows), or 4 bytes in UTF-32 format. Since this + * handles Unicode, it expects the string to be well-formed and not a + * null-terminated string of arbitrary bytes. Characters that are not valid + * UTF-16 (or UTF-32) are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * Note that while this function might deal with variable-sized characters, + * `maxlen` specifies a _wchar_ limit! If the limit lands in the middle of a + * multi-byte UTF-16 sequence, it may convert a portion of the final character + * to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not + * to overflow a buffer. + * + * `maxlen` specifies a maximum number of wchar_t values to compare; if the + * strings match to this number of wchar_t (or both have matched to a + * null-terminator character before this number of bytes), they will be + * considered equal. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \param maxlen the maximum number of wchar_t values to compare. + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); + +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ +extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); + +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * 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`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \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 + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \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 + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \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 + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); + +/** + * Convert a string to uppercase. + * + * **WARNING**: Regardless of system locale, this will only convert ASCII + * values 'A' through 'Z' to uppercase. + * + * This function operates on a null-terminated string of bytes--even if it is + * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their + * uppercase equivalents in-place, returning the original `str` pointer. + * + * \param str the string to convert in-place. Can not be NULL. + * \returns the `str` pointer passed into this function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlwr + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); + +/** + * Convert a string to lowercase. + * + * **WARNING**: Regardless of system locale, this will only convert ASCII + * values 'A' through 'Z' to lowercase. + * + * This function operates on a null-terminated string of bytes--even if it is + * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their + * lowercase equivalents in-place, returning the original `str` pointer. + * + * \param str the string to convert in-place. Can not be NULL. + * \returns the `str` pointer passed into this function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strupr + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); + +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` 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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` 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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a 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 _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the 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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, 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, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes 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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the 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.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); + +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); + +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ +extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ +extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \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. + * \param base The base of the integer to read. Supported values are 0 and 2 + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ +extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \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. + * \param base The base of the integer to read. Supported values are 0 and 2 + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \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. + * \param base The base of the integer to read. Supported values are 0 and 2 + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \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. + * \param base The base of the integer to read. Supported values are 0 and 2 + * 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 + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - 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. + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ +extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); + +/** + * Compare two null-terminated UTF-8 strings. + * + * Due to the nature of UTF-8 encoding, this will work with Unicode strings, + * since effectively this function just compares bytes until it hits a + * null-terminating character. Also due to the nature of UTF-8, this can be + * used with SDL_qsort() to put strings in (roughly) alphabetical order. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); + +/** + * Compare two UTF-8 strings up to a number of bytes. + * + * Due to the nature of UTF-8 encoding, this will work with Unicode strings, + * since effectively this function just compares bytes until it hits a + * null-terminating character. Also due to the nature of UTF-8, this can be + * used with SDL_qsort() to put strings in (roughly) alphabetical order. + * + * Note that while this function is intended to be used with UTF-8, it is + * doing a bytewise comparison, and `maxlen` specifies a _byte_ limit! If the + * limit lands in the middle of a multi-byte UTF-8 sequence, it will only + * compare a portion of the final character. + * + * `maxlen` specifies a maximum number of bytes to compare; if the strings + * match to this number of bytes (or both have matched to a null-terminator + * character before this number of bytes), they will be considered equal. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \param maxlen the maximum number of _bytes_ to compare. + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); + +/** + * Compare two null-terminated UTF-8 strings, case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the string to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); + + +/** + * Compare two UTF-8 strings, case-insensitively, up to a number of bytes. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the string to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * Note that while this function is intended to be used with UTF-8, `maxlen` + * specifies a _byte_ limit! If the limit lands in the middle of a multi-byte + * UTF-8 sequence, it may convert a portion of the final character to one or + * more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow + * a buffer. + * + * `maxlen` specifies a maximum number of bytes to compare; if the strings + * match to this number of bytes (or both have matched to a null-terminator + * character before this number of bytes), they will be considered equal. + * + * \param str1 the first string to compare. NULL is not permitted! + * \param str2 the second string to compare. NULL is not permitted! + * \param maxlen the maximum number of bytes to compare. + * \returns less than zero if str1 is "less than" str2, greater than zero if + * str1 is "greater than" str2, and zero if the strings match + * exactly. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); + +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + +/** + * The Unicode REPLACEMENT CHARACTER codepoint. + * + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. + * + * This tends to render as something like a question mark in most places. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_StepBackUTF8 + * \sa SDL_StepUTF8 + */ +#define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD + +/** + * Decode a UTF-8 string, one Unicode codepoint at a time. + * + * This will return the first Unicode codepoint in the UTF-8 encoded string in + * `*pstr`, and then advance `*pstr` past any consumed bytes before returning. + * + * It will not access more than `*pslen` bytes from the string. `*pslen` will + * be adjusted, as well, subtracting the number of bytes consumed. + * + * `pslen` is allowed to be NULL, in which case the string _must_ be + * NULL-terminated, as the function will blindly read until it sees the NULL + * char. + * + * if `*pslen` is zero, it assumes the end of string is reached and returns a + * zero codepoint regardless of the contents of the string buffer. + * + * If the resulting codepoint is zero (a NULL terminator), or `*pslen` is + * zero, it will not advance `*pstr` or `*pslen` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameters each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte + * (which is to say, a multibyte sequence might produce several + * SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid + * UTF-8 sequence). + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \param pslen a pointer to the number of bytes in the string, to be read and + * adjusted. NULL is allowed. + * \returns the first Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); + +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + +/** + * Convert a single Unicode codepoint to UTF-8. + * + * The buffer pointed to by `dst` must be at least 4 bytes long, as this + * function may generate between 1 and 4 bytes of output. + * + * This function returns the first byte _after_ the newly-written UTF-8 + * sequence, which is useful for encoding multiple codepoints in a loop, or + * knowing where to write a NULL-terminator character to end the string (in + * either case, plan to have a buffer of _more_ than 4 bytes!). + * + * If `codepoint` is an invalid value (outside the Unicode range, or a UTF-16 + * surrogate value, etc), this will use U+FFFD (REPLACEMENT CHARACTER) for the + * codepoint instead, and not set an error. + * + * If `dst` is NULL, this returns NULL immediately without writing to the + * pointer and without setting an error. + * + * \param codepoint a Unicode codepoint to convert to UTF-8. + * \param dst the location to write the encoded UTF-8. Must point to at least + * 4 bytes! + * \returns the first byte past the newly-written UTF-8 sequence. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +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.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + +/** + * Seeds the pseudo-random number generator. + * + * Reusing the seed number will cause SDL_rand() to repeat the same stream of + * 'random' numbers. + * + * \param seed the value to use as a random number seed, or 0 to use + * SDL_GetPerformanceCounter(). + * + * \threadsafety This should be called on the same thread that calls + * SDL_rand() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_rand + * \sa SDL_rand_bits + * \sa SDL_randf + */ +extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); + +/** + * Generate a pseudo-random number less than n for positive n + * + * The method used is faster and of better quality than `rand() % n`. Odds are + * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and + * much worse as n gets bigger. + * + * Example: to simulate a d6 use `SDL_rand(6) + 1` The +1 converts 0..5 to + * 1..6 + * + * If you want to generate a pseudo-random number in the full range of Sint32, + * you should use: (Sint32)SDL_rand_bits() + * + * If you want reproducible output, be sure to initialize with SDL_srand() + * first. + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \param n the number of possible outcomes. n must be positive. + * \returns a random value in the range of [0 .. n-1]. + * + * \threadsafety All calls should be made from a single thread + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_srand + * \sa SDL_randf + */ +extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); + +/** + * Generate a uniform pseudo-random floating point number less than 1.0 + * + * If you want reproducible output, be sure to initialize with SDL_srand() + * first. + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \returns a random value in the range of [0.0, 1.0). + * + * \threadsafety All calls should be made from a single thread + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_srand + * \sa SDL_rand + */ +extern SDL_DECLSPEC float SDLCALL SDL_randf(void); + +/** + * Generate 32 pseudo-random bits. + * + * You likely want to use SDL_rand() to get a psuedo-random number instead. + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \returns a random value in the range of [0-SDL_MAX_UINT32]. + * + * \threadsafety All calls should be made from a single thread + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_rand + * \sa SDL_randf + * \sa SDL_srand + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); + +/** + * Generate a pseudo-random number less than n for positive n + * + * The method used is faster and of better quality than `rand() % n`. Odds are + * roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and + * much worse as n gets bigger. + * + * Example: to simulate a d6 use `SDL_rand_r(state, 6) + 1` The +1 converts + * 0..5 to 1..6 + * + * If you want to generate a pseudo-random number in the full range of Sint32, + * you should use: (Sint32)SDL_rand_bits_r(state) + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \param state a pointer to the current random number state, this may not be + * NULL. + * \param n the number of possible outcomes. n must be positive. + * \returns a random value in the range of [0 .. n-1]. + * + * \threadsafety This function is thread-safe, as long as the state pointer + * isn't shared between threads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_rand + * \sa SDL_rand_bits_r + * \sa SDL_randf_r + */ +extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); + +/** + * Generate a uniform pseudo-random floating point number less than 1.0 + * + * If you want reproducible output, be sure to initialize with SDL_srand() + * first. + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \param state a pointer to the current random number state, this may not be + * NULL. + * \returns a random value in the range of [0.0, 1.0). + * + * \threadsafety This function is thread-safe, as long as the state pointer + * isn't shared between threads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_rand_bits_r + * \sa SDL_rand_r + * \sa SDL_randf + */ +extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); + +/** + * Generate 32 pseudo-random bits. + * + * You likely want to use SDL_rand_r() to get a psuedo-random number instead. + * + * There are no guarantees as to the quality of the random sequence produced, + * and this should not be used for security (cryptography, passwords) or where + * money is on the line (loot-boxes, casinos). There are many random number + * libraries available with different characteristics and you should pick one + * of those to meet any serious needs. + * + * \param state a pointer to the current random number state, this may not be + * NULL. + * \returns a random value in the range of [0-SDL_MAX_UINT32]. + * + * \threadsafety This function is thread-safe, as long as the state pointer + * isn't shared between threads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_rand_r + * \sa SDL_randf_r + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); + +#ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ +#define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ +#endif + +#ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ +#define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ +#endif + +/** + * Compute the arc cosine of `x`. + * + * The definition of `y = acos(x)` is `x = cos(y)`. + * + * Domain: `-1 <= x <= 1` + * + * Range: `0 <= y <= Pi` + * + * This function operates on double-precision floating point values, use + * SDL_acosf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc cosine of `x`, in radians. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_acosf + * \sa SDL_asin + * \sa SDL_cos + */ +extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); + +/** + * Compute the arc cosine of `x`. + * + * The definition of `y = acos(x)` is `x = cos(y)`. + * + * Domain: `-1 <= x <= 1` + * + * Range: `0 <= y <= Pi` + * + * This function operates on single-precision floating point values, use + * SDL_acos for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc cosine of `x`, in radians. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_acos + * \sa SDL_asinf + * \sa SDL_cosf + */ +extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); + +/** + * Compute the arc sine of `x`. + * + * The definition of `y = asin(x)` is `x = sin(y)`. + * + * Domain: `-1 <= x <= 1` + * + * Range: `-Pi/2 <= y <= Pi/2` + * + * This function operates on double-precision floating point values, use + * SDL_asinf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc sine of `x`, in radians. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_asinf + * \sa SDL_acos + * \sa SDL_sin + */ +extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); + +/** + * Compute the arc sine of `x`. + * + * The definition of `y = asin(x)` is `x = sin(y)`. + * + * Domain: `-1 <= x <= 1` + * + * Range: `-Pi/2 <= y <= Pi/2` + * + * This function operates on single-precision floating point values, use + * SDL_asin for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc sine of `x`, in radians. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_asin + * \sa SDL_acosf + * \sa SDL_sinf + */ +extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); + +/** + * Compute the arc tangent of `x`. + * + * The definition of `y = atan(x)` is `x = tan(y)`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-Pi/2 <= y <= Pi/2` + * + * This function operates on double-precision floating point values, use + * SDL_atanf for single-precision floats. + * + * To calculate the arc tangent of y / x, use SDL_atan2. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc tangent of of `x` in radians, or 0 if `x = 0`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atanf + * \sa SDL_atan2 + * \sa SDL_tan + */ +extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); + +/** + * Compute the arc tangent of `x`. + * + * The definition of `y = atan(x)` is `x = tan(y)`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-Pi/2 <= y <= Pi/2` + * + * This function operates on single-precision floating point values, use + * SDL_atan for dboule-precision floats. + * + * To calculate the arc tangent of y / x, use SDL_atan2f. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns arc tangent of of `x` in radians, or 0 if `x = 0`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atan + * \sa SDL_atan2f + * \sa SDL_tanf + */ +extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); + +/** + * Compute the arc tangent of `y / x`, using the signs of x and y to adjust + * the result's quadrant. + * + * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant + * of z is determined based on the signs of x and y. + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` + * + * Range: `-Pi <= y <= Pi` + * + * This function operates on double-precision floating point values, use + * SDL_atan2f for single-precision floats. + * + * To calculate the arc tangent of a single value, use SDL_atan. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param y floating point value of the numerator (y coordinate). + * \param x floating point value of the denominator (x coordinate). + * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either + * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atan2f + * \sa SDL_atan + * \sa SDL_tan + */ +extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); + +/** + * Compute the arc tangent of `y / x`, using the signs of x and y to adjust + * the result's quadrant. + * + * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant + * of z is determined based on the signs of x and y. + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` + * + * Range: `-Pi <= y <= Pi` + * + * This function operates on single-precision floating point values, use + * SDL_atan2 for double-precision floats. + * + * To calculate the arc tangent of a single value, use SDL_atanf. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param y floating point value of the numerator (y coordinate). + * \param x floating point value of the denominator (x coordinate). + * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either + * `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atan2 + * \sa SDL_atan + * \sa SDL_tan + */ +extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); + +/** + * Compute the ceiling of `x`. + * + * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x` + * rounded up to the nearest integer. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on double-precision floating point values, use + * SDL_ceilf for single-precision floats. + * + * \param x floating point value. + * \returns the ceiling of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ceilf + * \sa SDL_floor + * \sa SDL_trunc + * \sa SDL_round + * \sa SDL_lround + */ +extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); + +/** + * Compute the ceiling of `x`. + * + * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x` + * rounded up to the nearest integer. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on single-precision floating point values, use + * SDL_ceil for double-precision floats. + * + * \param x floating point value. + * \returns the ceiling of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ceil + * \sa SDL_floorf + * \sa SDL_truncf + * \sa SDL_roundf + * \sa SDL_lroundf + */ +extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); + +/** + * Copy the sign of one floating-point value to another. + * + * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``. + * + * Domain: `-INF <= x <= INF`, ``-INF <= y <= f`` + * + * Range: `-INF <= z <= INF` + * + * This function operates on double-precision floating point values, use + * SDL_copysignf for single-precision floats. + * + * \param x floating point value to use as the magnitude. + * \param y floating point value to use as the sign. + * \returns the floating point value with the sign of y and the magnitude of + * x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_copysignf + * \sa SDL_fabs + */ +extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); + +/** + * Copy the sign of one floating-point value to another. + * + * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``. + * + * Domain: `-INF <= x <= INF`, ``-INF <= y <= f`` + * + * Range: `-INF <= z <= INF` + * + * This function operates on single-precision floating point values, use + * SDL_copysign for double-precision floats. + * + * \param x floating point value to use as the magnitude. + * \param y floating point value to use as the sign. + * \returns the floating point value with the sign of y and the magnitude of + * x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_copysign + * \sa SDL_fabsf + */ +extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); + +/** + * Compute the cosine of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-1 <= y <= 1` + * + * This function operates on double-precision floating point values, use + * SDL_cosf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns cosine of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_cosf + * \sa SDL_acos + * \sa SDL_sin + */ +extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); + +/** + * Compute the cosine of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-1 <= y <= 1` + * + * This function operates on single-precision floating point values, use + * SDL_cos for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns cosine of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_cos + * \sa SDL_acosf + * \sa SDL_sinf + */ +extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); + +/** + * Compute the exponential of `x`. + * + * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the + * natural logarithm. The inverse is the natural logarithm, SDL_log. + * + * Domain: `-INF <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * The output will overflow if `exp(x)` is too large to be represented. + * + * This function operates on double-precision floating point values, use + * SDL_expf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns value of `e^x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_expf + * \sa SDL_log + */ +extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); + +/** + * Compute the exponential of `x`. + * + * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the + * natural logarithm. The inverse is the natural logarithm, SDL_logf. + * + * Domain: `-INF <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * The output will overflow if `exp(x)` is too large to be represented. + * + * This function operates on single-precision floating point values, use + * SDL_exp for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. + * \returns value of `e^x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_exp + * \sa SDL_logf + */ +extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); + +/** + * Compute the absolute value of `x` + * + * Domain: `-INF <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * This function operates on double-precision floating point values, use + * SDL_fabsf for single-precision floats. + * + * \param x floating point value to use as the magnitude. + * \returns the absolute value of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_fabsf + */ +extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); + +/** + * Compute the absolute value of `x` + * + * Domain: `-INF <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * This function operates on single-precision floating point values, use + * SDL_fabs for double-precision floats. + * + * \param x floating point value to use as the magnitude. + * \returns the absolute value of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_fabs + */ +extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); + +/** + * Compute the floor of `x`. + * + * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x` + * rounded down to the nearest integer. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on double-precision floating point values, use + * SDL_floorf for single-precision floats. + * + * \param x floating point value. + * \returns the floor of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_floorf + * \sa SDL_ceil + * \sa SDL_trunc + * \sa SDL_round + * \sa SDL_lround + */ +extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); + +/** + * Compute the floor of `x`. + * + * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x` + * rounded down to the nearest integer. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on single-precision floating point values, use + * SDL_floor for double-precision floats. + * + * \param x floating point value. + * \returns the floor of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_floor + * \sa SDL_ceilf + * \sa SDL_truncf + * \sa SDL_roundf + * \sa SDL_lroundf + */ +extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); + +/** + * Truncate `x` to an integer. + * + * Rounds `x` to the next closest integer to 0. This is equivalent to removing + * the fractional part of `x`, leaving only the integer part. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on double-precision floating point values, use + * SDL_truncf for single-precision floats. + * + * \param x floating point value. + * \returns `x` truncated to an integer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_truncf + * \sa SDL_fmod + * \sa SDL_ceil + * \sa SDL_floor + * \sa SDL_round + * \sa SDL_lround + */ +extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); + +/** + * Truncate `x` to an integer. + * + * Rounds `x` to the next closest integer to 0. This is equivalent to removing + * the fractional part of `x`, leaving only the integer part. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on single-precision floating point values, use + * SDL_trunc for double-precision floats. + * + * \param x floating point value. + * \returns `x` truncated to an integer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_trunc + * \sa SDL_fmodf + * \sa SDL_ceilf + * \sa SDL_floorf + * \sa SDL_roundf + * \sa SDL_lroundf + */ +extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); + +/** + * Return the floating-point remainder of `x / y` + * + * Divides `x` by `y`, and returns the remainder. + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0` + * + * Range: `-y <= z <= y` + * + * This function operates on double-precision floating point values, use + * SDL_fmodf for single-precision floats. + * + * \param x the numerator. + * \param y the denominator. Must not be 0. + * \returns the remainder of `x / y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_fmodf + * \sa SDL_modf + * \sa SDL_trunc + * \sa SDL_ceil + * \sa SDL_floor + * \sa SDL_round + * \sa SDL_lround + */ +extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); + +/** + * Return the floating-point remainder of `x / y` + * + * Divides `x` by `y`, and returns the remainder. + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0` + * + * Range: `-y <= z <= y` + * + * This function operates on single-precision floating point values, use + * SDL_fmod for double-precision floats. + * + * \param x the numerator. + * \param y the denominator. Must not be 0. + * \returns the remainder of `x / y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_fmod + * \sa SDL_truncf + * \sa SDL_modff + * \sa SDL_ceilf + * \sa SDL_floorf + * \sa SDL_roundf + * \sa SDL_lroundf + */ +extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); + +/** + * Return whether the value is infinity. + * + * \param x double-precision floating point value. + * \returns non-zero if the value is infinity, 0 otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isinff + */ +extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); + +/** + * Return whether the value is infinity. + * + * \param x floating point value. + * \returns non-zero if the value is infinity, 0 otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isinf + */ +extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); + +/** + * Return whether the value is NaN. + * + * \param x double-precision floating point value. + * \returns non-zero if the value is NaN, 0 otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isnanf + */ +extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); + +/** + * Return whether the value is NaN. + * + * \param x floating point value. + * \returns non-zero if the value is NaN, 0 otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_isnan + */ +extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); + +/** + * Compute the natural logarithm of `x`. + * + * Domain: `0 < x <= INF` + * + * Range: `-INF <= y <= INF` + * + * It is an error for `x` to be less than or equal to 0. + * + * This function operates on double-precision floating point values, use + * SDL_logf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than 0. + * \returns the natural logarithm of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_logf + * \sa SDL_log10 + * \sa SDL_exp + */ +extern SDL_DECLSPEC double SDLCALL SDL_log(double x); + +/** + * Compute the natural logarithm of `x`. + * + * Domain: `0 < x <= INF` + * + * Range: `-INF <= y <= INF` + * + * It is an error for `x` to be less than or equal to 0. + * + * This function operates on single-precision floating point values, use + * SDL_log for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than 0. + * \returns the natural logarithm of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_log + * \sa SDL_expf + */ +extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); + +/** + * Compute the base-10 logarithm of `x`. + * + * Domain: `0 < x <= INF` + * + * Range: `-INF <= y <= INF` + * + * It is an error for `x` to be less than or equal to 0. + * + * This function operates on double-precision floating point values, use + * SDL_log10f for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than 0. + * \returns the logarithm of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_log10f + * \sa SDL_log + * \sa SDL_pow + */ +extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); + +/** + * Compute the base-10 logarithm of `x`. + * + * Domain: `0 < x <= INF` + * + * Range: `-INF <= y <= INF` + * + * It is an error for `x` to be less than or equal to 0. + * + * This function operates on single-precision floating point values, use + * SDL_log10 for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than 0. + * \returns the logarithm of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_log10 + * \sa SDL_logf + * \sa SDL_powf + */ +extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); + +/** + * Split `x` into integer and fractional parts + * + * This function operates on double-precision floating point values, use + * SDL_modff for single-precision floats. + * + * \param x floating point value. + * \param y output pointer to store the integer part of `x`. + * \returns the fractional part of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_modff + * \sa SDL_trunc + * \sa SDL_fmod + */ +extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); + +/** + * Split `x` into integer and fractional parts + * + * This function operates on single-precision floating point values, use + * SDL_modf for double-precision floats. + * + * \param x floating point value. + * \param y output pointer to store the integer part of `x`. + * \returns the fractional part of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_modf + * \sa SDL_truncf + * \sa SDL_fmodf + */ +extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); + +/** + * Raise `x` to the power `y` + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` + * + * Range: `-INF <= z <= INF` + * + * If `y` is the base of the natural logarithm (e), consider using SDL_exp + * instead. + * + * This function operates on double-precision floating point values, use + * SDL_powf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x the base. + * \param y the exponent. + * \returns `x` raised to the power `y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_powf + * \sa SDL_exp + * \sa SDL_log + */ +extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); + +/** + * Raise `x` to the power `y` + * + * Domain: `-INF <= x <= INF`, `-INF <= y <= INF` + * + * Range: `-INF <= z <= INF` + * + * If `y` is the base of the natural logarithm (e), consider using SDL_exp + * instead. + * + * This function operates on single-precision floating point values, use + * SDL_pow for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x the base. + * \param y the exponent. + * \returns `x` raised to the power `y`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_pow + * \sa SDL_expf + * \sa SDL_logf + */ +extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); + +/** + * Round `x` to the nearest integer. + * + * Rounds `x` to the nearest integer. Values halfway between integers will be + * rounded away from zero. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on double-precision floating point values, use + * SDL_roundf for single-precision floats. To get the result as an integer + * type, use SDL_lround. + * + * \param x floating point value. + * \returns the nearest integer to `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_roundf + * \sa SDL_lround + * \sa SDL_floor + * \sa SDL_ceil + * \sa SDL_trunc + */ +extern SDL_DECLSPEC double SDLCALL SDL_round(double x); + +/** + * Round `x` to the nearest integer. + * + * Rounds `x` to the nearest integer. Values halfway between integers will be + * rounded away from zero. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF`, y integer + * + * This function operates on single-precision floating point values, use + * SDL_round for double-precision floats. To get the result as an integer + * type, use SDL_lroundf. + * + * \param x floating point value. + * \returns the nearest integer to `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_round + * \sa SDL_lroundf + * \sa SDL_floorf + * \sa SDL_ceilf + * \sa SDL_truncf + */ +extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); + +/** + * Round `x` to the nearest integer representable as a long + * + * Rounds `x` to the nearest integer. Values halfway between integers will be + * rounded away from zero. + * + * Domain: `-INF <= x <= INF` + * + * Range: `MIN_LONG <= y <= MAX_LONG` + * + * This function operates on double-precision floating point values, use + * SDL_lroundf for single-precision floats. To get the result as a + * floating-point type, use SDL_round. + * + * \param x floating point value. + * \returns the nearest integer to `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lroundf + * \sa SDL_round + * \sa SDL_floor + * \sa SDL_ceil + * \sa SDL_trunc + */ +extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); + +/** + * Round `x` to the nearest integer representable as a long + * + * Rounds `x` to the nearest integer. Values halfway between integers will be + * rounded away from zero. + * + * Domain: `-INF <= x <= INF` + * + * Range: `MIN_LONG <= y <= MAX_LONG` + * + * This function operates on single-precision floating point values, use + * SDL_lround for double-precision floats. To get the result as a + * floating-point type, use SDL_roundf. + * + * \param x floating point value. + * \returns the nearest integer to `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lround + * \sa SDL_roundf + * \sa SDL_floorf + * \sa SDL_ceilf + * \sa SDL_truncf + */ +extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); + +/** + * Scale `x` by an integer power of two. + * + * Multiplies `x` by the `n`th power of the floating point radix (always 2). + * + * Domain: `-INF <= x <= INF`, `n` integer + * + * Range: `-INF <= y <= INF` + * + * This function operates on double-precision floating point values, use + * SDL_scalbnf for single-precision floats. + * + * \param x floating point value to be scaled. + * \param n integer exponent. + * \returns `x * 2^n`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_scalbnf + * \sa SDL_pow + */ +extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); + +/** + * Scale `x` by an integer power of two. + * + * Multiplies `x` by the `n`th power of the floating point radix (always 2). + * + * Domain: `-INF <= x <= INF`, `n` integer + * + * Range: `-INF <= y <= INF` + * + * This function operates on single-precision floating point values, use + * SDL_scalbn for double-precision floats. + * + * \param x floating point value to be scaled. + * \param n integer exponent. + * \returns `x * 2^n`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_scalbn + * \sa SDL_powf + */ +extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); + +/** + * Compute the sine of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-1 <= y <= 1` + * + * This function operates on double-precision floating point values, use + * SDL_sinf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns sine of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_sinf + * \sa SDL_asin + * \sa SDL_cos + */ +extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); + +/** + * Compute the sine of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-1 <= y <= 1` + * + * This function operates on single-precision floating point values, use + * SDL_sin for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns sine of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_sin + * \sa SDL_asinf + * \sa SDL_cosf + */ +extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); + +/** + * Compute the square root of `x`. + * + * Domain: `0 <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * This function operates on double-precision floating point values, use + * SDL_sqrtf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than or equal to 0. + * \returns square root of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_sqrtf + */ +extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); + +/** + * Compute the square root of `x`. + * + * Domain: `0 <= x <= INF` + * + * Range: `0 <= y <= INF` + * + * This function operates on single-precision floating point values, use + * SDL_sqrt for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value. Must be greater than or equal to 0. + * \returns square root of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_sqrt + */ +extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); + +/** + * Compute the tangent of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF` + * + * This function operates on double-precision floating point values, use + * SDL_tanf for single-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns tangent of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_tanf + * \sa SDL_sin + * \sa SDL_cos + * \sa SDL_atan + * \sa SDL_atan2 + */ +extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); + +/** + * Compute the tangent of `x`. + * + * Domain: `-INF <= x <= INF` + * + * Range: `-INF <= y <= INF` + * + * This function operates on single-precision floating point values, use + * SDL_tan for double-precision floats. + * + * This function may use a different approximation across different versions, + * platforms and configurations. i.e, it can return a different value given + * the same input on different machines or operating systems, or if SDL is + * updated. + * + * \param x floating point value, in radians. + * \returns tangent of `x`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_tan + * \sa SDL_sinf + * \sa SDL_cosf + * \sa SDL_atanf + * \sa SDL_atan2f + */ +extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); + +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ +typedef struct SDL_iconv_data_t *SDL_iconv_t; + +/** + * This function allocates a context for the specified character set + * conversion. + * + * \param tocode The target character encoding, must not be NULL. + * \param fromcode The source character encoding, must not be NULL. + * \returns a handle that must be freed with SDL_iconv_close, or + * SDL_ICONV_ERROR on failure. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ +extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, + const char *fromcode); + +/** + * This function frees a context used for character set conversion. + * + * \param cd The character set conversion handle. + * \returns 0 on success, or -1 on failure. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_open + * \sa SDL_iconv_string + */ +extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); + +/** + * This function converts text between encodings, reading from and writing to + * a buffer. + * + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. + * + * \param cd The character set conversion context, created in + * SDL_iconv_open(). + * \param inbuf Address of variable that points to the first character of the + * input sequence. + * \param inbytesleft The number of bytes in the input buffer. + * \param outbuf Address of variable that points to the output buffer. + * \param outbytesleft The number of bytes in the output buffer. + * \returns the number of conversions on success, or a negative error code. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ +extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, + size_t *inbytesleft, char **outbuf, + size_t *outbytesleft); + +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + +/** + * Helper function to convert a string's encoding in one call. + * + * This function converts a buffer or string between encodings in one pass. + * + * The string does not need to be NULL-terminated; this function operates on + * the number of bytes specified in `inbytesleft` whether there is a NULL + * character anywhere in the buffer. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param tocode the character encoding of the output string. Examples are + * "UTF-8", "UCS-4", etc. + * \param fromcode the character encoding of data in `inbuf`. + * \param inbuf the string to convert to a different encoding. + * \param inbytesleft the size of the input string _in bytes_. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv + */ +extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, + const char *fromcode, + const char *inbuf, + size_t inbytesleft); + +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + + +/* force builds using Clang's static analysis tools to use literal C runtime + here, since there are possibly tests that are ineffective otherwise. */ +#if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) + +/* The analyzer knows about strlcpy even when the system doesn't provide it */ +#if !defined(HAVE_STRLCPY) && !defined(strlcpy) +size_t strlcpy(char *dst, const char *src, size_t size); +#endif + +/* The analyzer knows about strlcat even when the system doesn't provide it */ +#if !defined(HAVE_STRLCAT) && !defined(strlcat) +size_t strlcat(char *dst, const char *src, size_t size); +#endif + +#if !defined(HAVE_WCSLCPY) && !defined(wcslcpy) +size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); +#endif + +#if !defined(HAVE_WCSLCAT) && !defined(wcslcat) +size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); +#endif + +#ifndef _WIN32 +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +/* not for windows: might conflict with string.h where strdup may have + * dllimport attribute: https://github.com/libsdl-org/SDL/issues/12948 */ +char *strdup(const char *str); +#endif + +/* Starting LLVM 16, the analyser errors out if these functions do not have + their prototype defined (clang-diagnostic-implicit-function-declaration) */ +#include +#include + +#define SDL_malloc malloc +#define SDL_calloc calloc +#define SDL_realloc realloc +#define SDL_free free +#ifndef SDL_memcpy +#define SDL_memcpy memcpy +#endif +#ifndef SDL_memmove +#define SDL_memmove memmove +#endif +#ifndef SDL_memset +#define SDL_memset memset +#endif +#define SDL_memcmp memcmp +#define SDL_strlcpy strlcpy +#define SDL_strlcat strlcat +#define SDL_strlen strlen +#define SDL_wcslen wcslen +#define SDL_wcslcpy wcslcpy +#define SDL_wcslcat wcslcat +#define SDL_strdup strdup +#define SDL_wcsdup wcsdup +#define SDL_strchr strchr +#define SDL_strrchr strrchr +#define SDL_strstr strstr +#define SDL_wcsstr wcsstr +#define SDL_strtok_r strtok_r +#define SDL_strcmp strcmp +#define SDL_wcscmp wcscmp +#define SDL_strncmp strncmp +#define SDL_wcsncmp wcsncmp +#define SDL_strcasecmp strcasecmp +#define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk +#define SDL_sscanf sscanf +#define SDL_vsscanf vsscanf +#define SDL_snprintf snprintf +#define SDL_vsnprintf vsnprintf +#endif + +/** + * Multiply two integers, checking for overflow. + * + * If `a * b` would overflow, return false. + * + * Otherwise store `a * b` via ret and return true. + * + * \param a the multiplicand. + * \param b the multiplier. + * \param ret on non-overflow output, stores the multiplication result, may + * not be NULL. + * \returns false on overflow, true if result is multiplied without overflow. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) +{ + if (a != 0 && b > SDL_SIZE_MAX / a) { + return false; + } + *ret = a * b; + return true; +} + +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +#if SDL_HAS_BUILTIN(__builtin_mul_overflow) +/* This needs to be wrapped in an inline rather than being a direct #define, + * because __builtin_mul_overflow() is type-generic, but we want to be + * consistent about interpreting a and b as size_t. */ +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) +{ + return (__builtin_mul_overflow(a, b, ret) == 0); +} +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) +#endif +#endif + +/** + * Add two integers, checking for overflow. + * + * If `a + b` would overflow, return false. + * + * Otherwise store `a + b` via ret and return true. + * + * \param a the first addend. + * \param b the second addend. + * \param ret on non-overflow output, stores the addition result, may not be + * NULL. + * \returns false on overflow, true if result is added without overflow. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) +{ + if (b > SDL_SIZE_MAX - a) { + return false; + } + *ret = a + b; + return true; +} + +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +#if SDL_HAS_BUILTIN(__builtin_add_overflow) +/* This needs to be wrapped in an inline rather than being a direct #define, + * the same as the call to __builtin_mul_overflow() above. */ +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) +{ + return (__builtin_add_overflow(a, b, ret) == 0); +} +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) +#endif +#endif + +/* This is a generic function pointer which should be cast to the type you expect */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) +typedef void *SDL_FunctionPointer; +#else +typedef void (*SDL_FunctionPointer)(void); +#endif + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_stdinc_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_storage.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_storage.h new file mode 100644 index 0000000000..6837ebaacf --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_storage.h @@ -0,0 +1,682 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryStorage + * + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. + */ + +#ifndef SDL_storage_h_ +#define SDL_storage_h_ + +#include +#include +#include +#include + +#include + +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Function interface for SDL_Storage. + * + * Apps that want to supply a custom implementation of SDL_Storage will fill + * in all the functions in this struct, and then pass it to SDL_OpenStorage to + * create a custom SDL_Storage object. + * + * It is not usually necessary to do this; SDL provides standard + * implementations for many things you might expect to do with an SDL_Storage. + * + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE + */ +typedef struct SDL_StorageInterface +{ + /* The version of this interface */ + Uint32 version; + + /* Called when the storage is closed */ + bool (SDLCALL *close)(void *userdata); + + /* Optional, returns whether the storage is currently ready for access */ + bool (SDLCALL *ready)(void *userdata); + + /* Enumerate a directory, optional for write-only storage */ + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + + /* Get path information, optional for write-only storage */ + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + + /* Read a file from storage, optional for write-only storage */ + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + + /* Write a file to storage, optional for read-only storage */ + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + + /* Create a directory, optional for read-only storage */ + bool (SDLCALL *mkdir)(void *userdata, const char *path); + + /* Remove a file or empty directory, optional for read-only storage */ + bool (SDLCALL *remove)(void *userdata, const char *path); + + /* Rename a path, optional for read-only storage */ + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + + /* Copy a file, optional for read-only storage */ + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + + /* Get the space remaining, optional for read-only storage */ + Uint64 (SDLCALL *space_remaining)(void *userdata); +} SDL_StorageInterface; + +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + +/** + * An abstract interface for filesystem access. + * + * This is an opaque datatype. One can create this object using standard SDL + * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create + * an object with a custom implementation using SDL_OpenStorage. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Storage SDL_Storage; + +/** + * Opens up a read-only container for the application's filesystem. + * + * \param override a path to override the backend's default title root. + * \param props a property list that may contain backend-specific information. + * \returns a title storage container on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_OpenUserStorage + * \sa SDL_ReadStorageFile + */ +extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props); + +/** + * Opens up a container for a user's unique read/write filesystem. + * + * While title storage can generally be kept open throughout runtime, user + * storage should only be opened when the client is ready to read/write files. + * This allows the backend to properly batch file operations and flush them + * when the container has been closed; ensuring safe and optimal save I/O. + * + * \param org the name of your organization. + * \param app the name of your application. + * \param props a property list that may contain backend-specific information. + * \returns a user storage container on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_OpenTitleStorage + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + */ +extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, const char *app, SDL_PropertiesID props); + +/** + * Opens up a container for local filesystem storage. + * + * This is provided for development and tools. Portable applications should + * use SDL_OpenTitleStorage() for access to game data and + * SDL_OpenUserStorage() for access to user data. + * + * \param path the base path prepended to all storage paths, or NULL for no + * base path. + * \returns a filesystem storage container on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_OpenTitleStorage + * \sa SDL_OpenUserStorage + * \sa SDL_ReadStorageFile + * \sa SDL_WriteStorageFile + */ +extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); + +/** + * Opens up a container using a client-provided storage interface. + * + * Applications do not need to use this function unless they are providing + * their own SDL_Storage implementation. If you just need an SDL_Storage, you + * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() + * or SDL_OpenUserStorage(). + * + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. + * \returns a storage container on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + */ +extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInterface *iface, void *userdata); + +/** + * Closes and frees a storage container. + * + * \param storage a storage container to close. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenFileStorage + * \sa SDL_OpenStorage + * \sa SDL_OpenTitleStorage + * \sa SDL_OpenUserStorage + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); + +/** + * Checks if the storage container is ready to use. + * + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. You might instead poll this in your + * game's main loop while processing events and drawing a loading screen. + * + * \param storage a storage container to query. + * \returns true if the container is ready, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); + +/** + * Query the size of a file within a storage container. + * + * \param storage a storage container to query. + * \param path the relative path of the file to query. + * \param length a pointer to be filled with the file's length. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); + +/** + * Synchronously read a file from a storage container into a client-provided + * buffer. + * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * + * \param storage a storage container to read from. + * \param path the relative path of the file to read. + * \param destination a client-provided buffer to read the file into. + * \param length the length of the destination buffer. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetStorageFileSize + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); + +/** + * Synchronously write a file from client memory into a storage container. + * + * \param storage a storage container to write to. + * \param path the relative path of the file to write. + * \param source a client-provided buffer to write from. + * \param length the length of the source buffer. + * \returns true if the file was written or false on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); + +/** + * Create a directory in a writable storage container. + * + * \param storage a storage container. + * \param path the path of the directory to create. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); + +/** + * Enumerate a directory in a storage container through a callback function. + * + * This function provides every directory entry through an app-provided + * callback, called once for each directory entry, until all results have been + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate, or NULL for the root. + * \param callback a function that is called for each entry in the directory. + * \param userdata a pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); + +/** + * Remove a file or an empty directory in a writable storage container. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); + +/** + * Rename a file or directory in a writable storage container. + * + * \param storage a storage container. + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); + +/** + * Copy a file in a writable storage container. + * + * \param storage a storage container. + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); + +/** + * Get information about a filesystem path in a storage container. + * + * \param storage a storage container. + * \param path the path to query. + * \param info a pointer filled in with information about the path, or NULL to + * check for the existence of a file. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); + +/** + * Queries the remaining space in a storage container. + * + * \param storage a storage container to query. + * \returns the amount of remaining space, in bytes. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *storage); + +/** + * Enumerate a directory tree, filtered by pattern, and return a list. + * + * Files are filtered out if they don't match the string in `pattern`, which + * may contain wildcard characters `*` (match everything) and `?` (match one + * character). If pattern is NULL, no filtering is done and all results are + * returned. Subdirectories are permitted, and are specified with a path + * separator of '/'. Wildcard characters `*` and `?` never match a path + * separator. + * + * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching + * case-insensitive. + * + * The returned array is always NULL-terminated, for your iterating + * convenience, but if `count` is non-NULL, on return it will contain the + * number of items in the array, not counting the NULL terminator. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate, or NULL for the root. + * \param pattern the pattern that files in the directory must match. Can be + * NULL. + * \param flags `SDL_GLOB_*` bitflags that affect this search. + * \param count on return, will be set to the number of items in the returned + * array. Can be NULL. + * \returns an array of strings on success or NULL on failure; call + * SDL_GetError() for more information. The caller should pass the + * returned pointer to SDL_free when done with it. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. + * + * \threadsafety It is safe to call this function from any thread, assuming + * the `storage` object is thread-safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_storage_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_surface.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_surface.h new file mode 100644 index 0000000000..15fce042f7 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_surface.h @@ -0,0 +1,1563 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategorySurface + * + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image + */ + +#ifndef SDL_surface_h_ +#define SDL_surface_h_ + +#include +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The flags on an SDL_Surface. + * + * These are generally considered read-only. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_SurfaceFlags; + +#define SDL_SURFACE_PREALLOCATED 0x00000001u /**< Surface uses preallocated pixel memory */ +#define SDL_SURFACE_LOCK_NEEDED 0x00000002u /**< Surface needs to be locked to access pixels */ +#define SDL_SURFACE_LOCKED 0x00000004u /**< Surface is currently locked */ +#define SDL_SURFACE_SIMD_ALIGNED 0x00000008u /**< Surface uses pixel memory allocated with SDL_aligned_alloc() */ + +/** + * Evaluates to true if the surface needs to be locked before access. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MUSTLOCK(S) (((S)->flags & SDL_SURFACE_LOCK_NEEDED) == SDL_SURFACE_LOCK_NEEDED) + +/** + * The scaling mode. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ScaleMode +{ + SDL_SCALEMODE_INVALID = -1, + SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */ + SDL_SCALEMODE_LINEAR /**< linear filtering */ +} SDL_ScaleMode; + +/** + * The flip mode. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_FlipMode +{ + SDL_FLIP_NONE, /**< Do not flip */ + SDL_FLIP_HORIZONTAL, /**< flip horizontally */ + SDL_FLIP_VERTICAL /**< flip vertically */ +} SDL_FlipMode; + +#ifndef SDL_INTERNAL + +/** + * A collection of pixels used in software blitting. + * + * Pixels are arranged in memory in rows, with the top row first. Each row + * occupies an amount of memory given by the pitch (sometimes known as the row + * stride in non-SDL APIs). + * + * Within each row, pixels are arranged from left to right until the width is + * reached. Each pixel occupies a number of bits appropriate for its format, + * with most formats representing each pixel as one or more whole bytes (in + * some indexed formats, instead multiple pixels are packed into each byte), + * and a byte order given by the format. After encoding all pixels, any + * remaining bytes to reach the pitch are used as padding to reach a desired + * alignment, and have undefined contents. + * + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * When a surface holds MJPG format data, pixels points at the compressed JPEG + * image and pitch is the length of that data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface + */ +struct SDL_Surface +{ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ + + int refcount; /**< Application reference count, used when freeing surface */ + + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ + +typedef struct SDL_Surface SDL_Surface; + +/** + * Allocate a new surface with a specific pixel format. + * + * The pixels of the new surface are initialized to zero. + * + * \param width the width of the surface. + * \param height the height of the surface. + * \param format the SDL_PixelFormat for the new surface's pixel format. + * \returns the new SDL_Surface structure that is created or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateSurfaceFrom + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int height, SDL_PixelFormat format); + +/** + * Allocate a new surface with a specific pixel format and existing pixel + * data. + * + * No copy is made of the pixel data. Pixel data is not managed automatically; + * you must free the surface before you free the pixel data. + * + * Pitch is the offset in bytes from one row of pixels to the next, e.g. + * `width*4` for `SDL_PIXELFORMAT_RGBA8888`. + * + * You may pass NULL for pixels and 0 for pitch to create a surface that you + * will fill in with valid values later. + * + * \param width the width of the surface. + * \param height the height of the surface. + * \param format the SDL_PixelFormat for the new surface's pixel format. + * \param pixels a pointer to existing pixel data. + * \param pitch the number of bytes between each row, including padding. + * \returns the new SDL_Surface structure that is created or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int height, SDL_PixelFormat format, void *pixels, int pitch); + +/** + * Free a surface. + * + * It is safe to pass NULL to this function. + * + * \param surface the SDL_Surface to free. + * + * \threadsafety No other thread should be using the surface when it is freed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_CreateSurfaceFrom + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); + +/** + * Get the properties associated with a surface. + * + * The following properties are understood by SDL: + * + * - `SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating point + * surfaces, this defines the value of 100% diffuse white, with higher + * values being displayed in the High Dynamic Range headroom. This defaults + * to 203 for HDR10 surfaces and 1.0 for floating point surfaces. + * - `SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT`: for HDR10 and floating point + * surfaces, this defines the maximum dynamic range used by the content, in + * terms of the SDR white point. This defaults to 0.0, which disables tone + * mapping. + * - `SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING`: the tone mapping operator + * used when compressing from a surface with high dynamic range to another + * with lower dynamic range. Currently this supports "chrome", which uses + * the same tone mapping that Chrome uses for HDR content, the form "*=N", + * where N is a floating point scale factor applied in linear space, and + * "none", which disables tone mapping. This defaults to "chrome". + * - `SDL_PROP_SURFACE_HOTSPOT_X_NUMBER`: the hotspot pixel offset from the + * left edge of the image, if this surface is being used as a cursor. + * - `SDL_PROP_SURFACE_HOTSPOT_Y_NUMBER`: the hotspot pixel offset from the + * top edge of the image, if this surface is being used as a cursor. + * + * \param surface the SDL_Surface structure to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); + +#define SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT "SDL.surface.SDR_white_point" +#define SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT "SDL.surface.HDR_headroom" +#define SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING "SDL.surface.tonemap" +#define SDL_PROP_SURFACE_HOTSPOT_X_NUMBER "SDL.surface.hotspot.x" +#define SDL_PROP_SURFACE_HOTSPOT_Y_NUMBER "SDL.surface.hotspot.y" + +/** + * Set the colorspace used by a surface. + * + * Setting the colorspace doesn't change the pixels, only how they are + * interpreted in color operations. + * + * \param surface the SDL_Surface structure to update. + * \param colorspace an SDL_Colorspace value describing the surface + * colorspace. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceColorspace + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); + +/** + * Get the colorspace used by a surface. + * + * The colorspace defaults to SDL_COLORSPACE_SRGB_LINEAR for floating point + * formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for + * other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures. + * + * \param surface the SDL_Surface structure to query. + * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if + * the surface is NULL. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceColorspace + */ +extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface); + +/** + * Create a palette and associate it with a surface. + * + * This function creates a palette compatible with the provided surface. The + * palette is then returned for you to modify, and the surface will + * automatically use the new palette in future operations. You do not need to + * destroy the returned palette, it will be freed when the reference count + * reaches 0, usually when the surface is destroyed. + * + * Bitmap surfaces (with format SDL_PIXELFORMAT_INDEX1LSB or + * SDL_PIXELFORMAT_INDEX1MSB) will have the palette initialized with 0 as + * white and 1 as black. Other surfaces will get a palette initialized with + * white in every entry. + * + * If this function is called for a surface that already has a palette, a new + * palette will be created to replace it. + * + * \param surface the SDL_Surface structure to update. + * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if + * the surface didn't have an index format); call SDL_GetError() for + * more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetPaletteColors + */ +extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface *surface); + +/** + * Set the palette used by a surface. + * + * A single palette can be shared with many surfaces. + * + * \param surface the SDL_Surface structure to update. + * \param palette the SDL_Palette structure to use. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreatePalette + * \sa SDL_GetSurfacePalette + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); + +/** + * Get the palette used by a surface. + * + * \param surface the SDL_Surface structure to query. + * \returns a pointer to the palette used by the surface, or NULL if there is + * no palette used. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfacePalette + */ +extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *surface); + +/** + * Add an alternate version of a surface. + * + * This function adds an alternate version of this surface, usually used for + * content with high DPI representations like cursors or icons. The size, + * format, and content do not need to match the original surface, and these + * alternate versions will not be updated when the original surface changes. + * + * This function adds a reference to the alternate version, so you should call + * SDL_DestroySurface() on the image after this call. + * + * \param surface the SDL_Surface structure to update. + * \param image a pointer to an alternate SDL_Surface to associate with this + * surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveSurfaceAlternateImages + * \sa SDL_GetSurfaceImages + * \sa SDL_SurfaceHasAlternateImages + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); + +/** + * Return whether a surface has alternate versions available. + * + * \param surface the SDL_Surface structure to query. + * \returns true if alternate versions are available or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddSurfaceAlternateImage + * \sa SDL_RemoveSurfaceAlternateImages + * \sa SDL_GetSurfaceImages + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); + +/** + * Get an array including all versions of a surface. + * + * This returns all versions of a surface, with the surface being queried as + * the first element in the returned array. + * + * Freeing the array of surfaces does not affect the surfaces in the array. + * They are still referenced by the surface being queried and will be cleaned + * up normally. + * + * \param surface the SDL_Surface structure to query. + * \param count a pointer filled in with the number of surface pointers + * returned, may be NULL. + * \returns a NULL terminated array of SDL_Surface pointers or NULL on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddSurfaceAlternateImage + * \sa SDL_RemoveSurfaceAlternateImages + * \sa SDL_SurfaceHasAlternateImages + */ +extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *surface, int *count); + +/** + * Remove all alternate versions of a surface. + * + * This function removes a reference from all the alternative versions, + * destroying them if this is the last reference to them. + * + * \param surface the SDL_Surface structure to update. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddSurfaceAlternateImage + * \sa SDL_GetSurfaceImages + * \sa SDL_SurfaceHasAlternateImages + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *surface); + +/** + * Set up a surface for directly accessing the pixels. + * + * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to + * and read from `surface->pixels`, using the pixel format stored in + * `surface->format`. Once you are done accessing the surface, you should use + * SDL_UnlockSurface() to release it. + * + * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to + * 0, then you can read and write to the surface at any time, and the pixel + * format of the surface will not change. + * + * \param surface the SDL_Surface structure to be locked. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. The locking referred to by + * this function is making the pixels available for direct + * access, not thread-safe locking. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MUSTLOCK + * \sa SDL_UnlockSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); + +/** + * Release a surface after directly accessing the pixels. + * + * \param surface the SDL_Surface structure to be unlocked. + * + * \threadsafety This function is not thread safe. The locking referred to by + * this function is making the pixels available for direct + * access, not thread-safe locking. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockSurface + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); + +/** + * Load a BMP image from a seekable SDL data stream. + * + * The new surface should be freed with SDL_DestroySurface(). Not doing so + * will result in a memory leak. + * + * \param src the data stream for the surface. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns a pointer to a new SDL_Surface structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadBMP + * \sa SDL_SaveBMP_IO + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); + +/** + * Load a BMP image from a file. + * + * The new surface should be freed with SDL_DestroySurface(). Not doing so + * will result in a memory leak. + * + * \param file the BMP file to load. + * \returns a pointer to a new SDL_Surface structure or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadBMP_IO + * \sa SDL_SaveBMP + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); + +/** + * Save a surface to a seekable SDL data stream in BMP format. + * + * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the + * BMP directly. Other RGB formats with 8-bit or higher get converted to a + * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit + * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are + * not supported. + * + * \param surface the SDL_Surface structure containing the image to be saved. + * \param dst a data stream to save to. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadBMP_IO + * \sa SDL_SaveBMP + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); + +/** + * Save a surface to a file. + * + * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the + * BMP directly. Other RGB formats with 8-bit or higher get converted to a + * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit + * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are + * not supported. + * + * \param surface the SDL_Surface structure containing the image to be saved. + * \param file a file to save to. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadBMP + * \sa SDL_SaveBMP_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); + +/** + * Set the RLE acceleration hint for a surface. + * + * If RLE is enabled, color key and alpha blending blits are much faster, but + * the surface must be locked before directly accessing the pixels. + * + * \param surface the SDL_Surface structure to optimize. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + * \sa SDL_LockSurface + * \sa SDL_UnlockSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); + +/** + * Returns whether the surface is RLE enabled. + * + * It is safe to pass a NULL `surface` here; it will return false. + * + * \param surface the SDL_Surface structure to query. + * \returns true if the surface is RLE enabled, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceRLE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); + +/** + * Set the color key (transparent pixel) in a surface. + * + * The color key defines a pixel value that will be treated as transparent in + * a blit. For example, one can use this to specify that cyan pixels should be + * considered transparent, and therefore not rendered. + * + * It is a pixel of the format used by the surface, as generated by + * SDL_MapRGB(). + * + * \param surface the SDL_Surface structure to update. + * \param enabled true to enable color key, false to disable color key. + * \param key the transparent pixel. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceColorKey + * \sa SDL_SetSurfaceRLE + * \sa SDL_SurfaceHasColorKey + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); + +/** + * Returns whether the surface has a color key. + * + * It is safe to pass a NULL `surface` here; it will return false. + * + * \param surface the SDL_Surface structure to query. + * \returns true if the surface has a color key, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceColorKey + * \sa SDL_GetSurfaceColorKey + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); + +/** + * Get the color key (transparent pixel) for a surface. + * + * The color key is a pixel of the format used by the surface, as generated by + * SDL_MapRGB(). + * + * If the surface doesn't have color key enabled this function returns false. + * + * \param surface the SDL_Surface structure to query. + * \param key a pointer filled in with the transparent pixel. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceColorKey + * \sa SDL_SurfaceHasColorKey + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); + +/** + * Set an additional color value multiplied into blit operations. + * + * When this surface is blitted, during the blit operation each source color + * channel is modulated by the appropriate color value according to the + * following formula: + * + * `srcC = srcC * (color / 255)` + * + * \param surface the SDL_Surface structure to update. + * \param r the red color value multiplied into blit operations. + * \param g the green color value multiplied into blit operations. + * \param b the blue color value multiplied into blit operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceColorMod + * \sa SDL_SetSurfaceAlphaMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); + + +/** + * Get the additional color value multiplied into blit operations. + * + * \param surface the SDL_Surface structure to query. + * \param r a pointer filled in with the current red color value. + * \param g a pointer filled in with the current green color value. + * \param b a pointer filled in with the current blue color value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceAlphaMod + * \sa SDL_SetSurfaceColorMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); + +/** + * Set an additional alpha value used in blit operations. + * + * When this surface is blitted, during the blit operation the source alpha + * value is modulated by this alpha value according to the following formula: + * + * `srcA = srcA * (alpha / 255)` + * + * \param surface the SDL_Surface structure to update. + * \param alpha the alpha value multiplied into blit operations. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceAlphaMod + * \sa SDL_SetSurfaceColorMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); + +/** + * Get the additional alpha value used in blit operations. + * + * \param surface the SDL_Surface structure to query. + * \param alpha a pointer filled in with the current alpha value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceColorMod + * \sa SDL_SetSurfaceAlphaMod + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); + +/** + * Set the blend mode used for blit operations. + * + * To copy a surface to another surface (or texture) without blending with the + * existing data, the blendmode of the SOURCE surface should be set to + * `SDL_BLENDMODE_NONE`. + * + * \param surface the SDL_Surface structure to update. + * \param blendMode the SDL_BlendMode to use for blit blending. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); + +/** + * Get the blend mode used for blit operations. + * + * \param surface the SDL_Surface structure to query. + * \param blendMode a pointer filled in with the current SDL_BlendMode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceBlendMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); + +/** + * Set the clipping rectangle for a surface. + * + * When `surface` is the destination of a blit, only the area within the clip + * rectangle is drawn into. + * + * Note that blits are automatically clipped to the edges of the source and + * destination surfaces. + * + * \param surface the SDL_Surface structure to be clipped. + * \param rect the SDL_Rect structure representing the clipping rectangle, or + * NULL to disable clipping. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetSurfaceClipRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); + +/** + * Get the clipping rectangle for a surface. + * + * When `surface` is the destination of a blit, only the area within the clip + * rectangle is drawn into. + * + * \param surface the SDL_Surface structure representing the surface to be + * clipped. + * \param rect an SDL_Rect structure filled in with the clipping rectangle for + * the surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetSurfaceClipRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); + +/** + * Flip a surface vertically or horizontally. + * + * \param surface the surface to flip. + * \param flip the direction to flip. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); + +/** + * Creates a new surface identical to the existing surface. + * + * If the original surface has alternate images, the new surface will have a + * reference to them as well. + * + * The returned surface should be freed with SDL_DestroySurface(). + * + * \param surface the surface to duplicate. + * \returns a copy of the surface or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surface); + +/** + * Creates a new surface identical to the existing surface, scaled to the + * desired size. + * + * The returned surface should be freed with SDL_DestroySurface(). + * + * \param surface the surface to duplicate and scale. + * \param width the width of the new surface. + * \param height the height of the new surface. + * \param scaleMode the SDL_ScaleMode to be used. + * \returns a copy of the surface or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, int width, int height, SDL_ScaleMode scaleMode); + +/** + * Copy an existing surface to a new surface of the specified format. + * + * This function is used to optimize images for faster *repeat* blitting. This + * is accomplished by converting the original and storing the result as a new + * surface. The new, optimized surface can then be used as the source for + * future blits, making them faster. + * + * If you are converting to an indexed surface and want to map colors to a + * palette, you can use SDL_ConvertSurfaceAndColorspace() instead. + * + * If the original surface has alternate images, the new surface will have a + * reference to them as well. + * + * \param surface the existing SDL_Surface structure to convert. + * \param format the new pixel format. + * \returns the new SDL_Surface structure that is created or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ConvertSurfaceAndColorspace + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surface, SDL_PixelFormat format); + +/** + * Copy an existing surface to a new surface of the specified format and + * colorspace. + * + * This function converts an existing surface to a new format and colorspace + * and returns the new surface. This will perform any pixel format and + * colorspace conversion needed. + * + * If the original surface has alternate images, the new surface will have a + * reference to them as well. + * + * \param surface the existing SDL_Surface structure to convert. + * \param format the new pixel format. + * \param palette an optional palette to use for indexed formats, may be NULL. + * \param colorspace the new colorspace. + * \param props an SDL_PropertiesID with additional color properties, or 0. + * \returns the new SDL_Surface structure that is created or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ConvertSurface + * \sa SDL_DestroySurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); + +/** + * Copy a block of pixels of one format to another format. + * + * \param width the width of the block to copy, in pixels. + * \param height the height of the block to copy, in pixels. + * \param src_format an SDL_PixelFormat value of the `src` pixels format. + * \param src a pointer to the source pixels. + * \param src_pitch the pitch of the source pixels, in bytes. + * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. + * \param dst a pointer to be filled in with new pixel data. + * \param dst_pitch the pitch of the destination pixels, in bytes. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ConvertPixelsAndColorspace + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); + +/** + * Copy a block of pixels of one format and colorspace to another format and + * colorspace. + * + * \param width the width of the block to copy, in pixels. + * \param height the height of the block to copy, in pixels. + * \param src_format an SDL_PixelFormat value of the `src` pixels format. + * \param src_colorspace an SDL_Colorspace value describing the colorspace of + * the `src` pixels. + * \param src_properties an SDL_PropertiesID with additional source color + * properties, or 0. + * \param src a pointer to the source pixels. + * \param src_pitch the pitch of the source pixels, in bytes. + * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of + * the `dst` pixels. + * \param dst_properties an SDL_PropertiesID with additional destination color + * properties, or 0. + * \param dst a pointer to be filled in with new pixel data. + * \param dst_pitch the pitch of the destination pixels, in bytes. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ConvertPixels + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); + +/** + * Premultiply the alpha on a block of pixels. + * + * This is safe to use with src == dst, but not for other overlapping areas. + * + * \param width the width of the block to convert, in pixels. + * \param height the height of the block to convert, in pixels. + * \param src_format an SDL_PixelFormat value of the `src` pixels format. + * \param src a pointer to the source pixels. + * \param src_pitch the pitch of the source pixels, in bytes. + * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. + * \param dst a pointer to be filled in with premultiplied pixel data. + * \param dst_pitch the pitch of the destination pixels, in bytes. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); + +/** + * Premultiply the alpha in a surface. + * + * This is safe to use with src == dst, but not for other overlapping areas. + * + * \param surface the surface to modify. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); + +/** + * Clear a surface with a specific color, with floating point precision. + * + * This function handles all surface formats, and ignores any clip rectangle. + * + * If the surface is YUV, the color is assumed to be in the sRGB colorspace, + * otherwise the color is assumed to be in the colorspace of the suface. + * + * \param surface the SDL_Surface to clear. + * \param r the red component of the pixel, normally in the range 0-1. + * \param g the green component of the pixel, normally in the range 0-1. + * \param b the blue component of the pixel, normally in the range 0-1. + * \param a the alpha component of the pixel, normally in the range 0-1. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); + +/** + * Perform a fast fill of a rectangle with a specific color. + * + * `color` should be a pixel of the format used by the surface, and can be + * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an + * alpha component then the destination is simply filled with that alpha + * information, no blending takes place. + * + * If there is a clip rectangle set on the destination (set via + * SDL_SetSurfaceClipRect()), then this function will fill based on the + * intersection of the clip rectangle and `rect`. + * + * \param dst the SDL_Surface structure that is the drawing target. + * \param rect the SDL_Rect structure representing the rectangle to fill, or + * NULL to fill the entire surface. + * \param color the color to fill with. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FillSurfaceRects + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); + +/** + * Perform a fast fill of a set of rectangles with a specific color. + * + * `color` should be a pixel of the format used by the surface, and can be + * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an + * alpha component then the destination is simply filled with that alpha + * information, no blending takes place. + * + * If there is a clip rectangle set on the destination (set via + * SDL_SetSurfaceClipRect()), then this function will fill based on the + * intersection of the clip rectangle and `rect`. + * + * \param dst the SDL_Surface structure that is the drawing target. + * \param rects an array of SDL_Rects representing the rectangles to fill. + * \param count the number of rectangles in the array. + * \param color the color to fill with. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FillSurfaceRect + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); + +/** + * Performs a fast blit from the source surface to the destination surface + * with clipping. + * + * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The blit function should not be called on a locked surface. + * + * The blit semantics for surfaces with and without blending and colorkey are + * defined as follows: + * + * ``` + * RGBA->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * if SDL_SRCCOLORKEY set, only copy the pixels that do not match the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB, set destination alpha to source per-surface alpha value. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels that do not match the + * source color key. + * + * RGBA->RGBA: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source alpha-channel and per-surface alpha) + * SDL_SRCCOLORKEY ignored. + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy all of RGBA to the destination. + * if SDL_SRCCOLORKEY set, only copy the pixels that do not match the + * RGB values of the source color key, ignoring alpha in the + * comparison. + * + * RGB->RGB: + * Source surface blend mode set to SDL_BLENDMODE_BLEND: + * alpha-blend (using the source per-surface alpha) + * Source surface blend mode set to SDL_BLENDMODE_NONE: + * copy RGB. + * both: + * if SDL_SRCCOLORKEY set, only copy the pixels that do not match the + * source color key. + * ``` + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, or NULL to copy the entire surface. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the x and y position in + * the destination surface, or NULL for (0,0). The width and + * height are ignored, and are copied from `srcrect`. If you + * want a specific width and height, you should use + * SDL_BlitSurfaceScaled(). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurfaceScaled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); + +/** + * Perform low-level surface blitting only. + * + * This is a semi-private blit function and it performs low-level surface + * blitting, assuming the input rectangles have already been clipped. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, may not be NULL. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, may not be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); + +/** + * Perform a scaled blit to a destination surface, which may be of a different + * format. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, or NULL to copy the entire surface. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, or NULL to fill the entire + * destination surface. + * \param scaleMode the SDL_ScaleMode to be used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); + +/** + * Perform low-level surface scaled blitting only. + * + * This is a semi-private function and it performs low-level surface blitting, + * assuming the input rectangles have already been clipped. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, may not be NULL. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, may not be NULL. + * \param scaleMode the SDL_ScaleMode to be used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurfaceScaled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); + +/** + * Perform a stretched pixel copy from one surface to another. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, or NULL to copy the entire surface. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, or NULL to fill the entire + * destination surface. + * \param scaleMode the SDL_ScaleMode to be used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_BlitSurfaceScaled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_StretchSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); + +/** + * Perform a tiled blit to a destination surface, which may be of a different + * format. + * + * The pixels in `srcrect` will be repeated as many times as needed to + * completely fill `dstrect`. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, or NULL to copy the entire surface. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, or NULL to fill the entire surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); + +/** + * Perform a scaled and tiled blit to a destination surface, which may be of a + * different format. + * + * The pixels in `srcrect` will be scaled and repeated as many times as needed + * to completely fill `dstrect`. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be + * copied, or NULL to copy the entire surface. + * \param scale the scale used to transform srcrect into the destination + * rectangle, e.g. a 32x32 texture with a scale of 2 would fill + * 64x64 tiles. + * \param scaleMode scale algorithm to be used. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, or NULL to fill the entire surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); + +/** + * Perform a scaled blit using the 9-grid algorithm to a destination surface, + * which may be of a different format. + * + * The pixels in the source surface are split into a 3x3 grid, using the + * different corner sizes for each corner, and the sides and center making up + * the remaining pixels. The corners are then scaled using `scale` and fit + * into the corners of the destination rectangle. The sides and center are + * then stretched into place to cover the remaining destination rectangle. + * + * \param src the SDL_Surface structure to be copied from. + * \param srcrect the SDL_Rect structure representing the rectangle to be used + * for the 9-grid, or NULL to use the entire surface. + * \param left_width the width, in pixels, of the left corners in `srcrect`. + * \param right_width the width, in pixels, of the right corners in `srcrect`. + * \param top_height the height, in pixels, of the top corners in `srcrect`. + * \param bottom_height the height, in pixels, of the bottom corners in + * `srcrect`. + * \param scale the scale used to transform the corner of `srcrect` into the + * corner of `dstrect`, or 0.0f for an unscaled blit. + * \param scaleMode scale algorithm to be used. + * \param dst the SDL_Surface structure that is the blit target. + * \param dstrect the SDL_Rect structure representing the target rectangle in + * the destination surface, or NULL to fill the entire surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BlitSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); + +/** + * Map an RGB triple to an opaque pixel value for a surface. + * + * This function maps the RGB color value to the specified pixel format and + * returns the pixel value best approximating the given RGB color value for + * the given pixel format. + * + * If the surface has a palette, the index of the closest matching color in + * the palette will be returned. + * + * If the surface pixel format has an alpha component it will be returned as + * all 1 bits (fully opaque). + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param surface the surface to use for the pixel format and palette. + * \param r the red component of the pixel in the range 0-255. + * \param g the green component of the pixel in the range 0-255. + * \param b the blue component of the pixel in the range 0-255. + * \returns a pixel value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MapSurfaceRGBA + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); + +/** + * Map an RGBA quadruple to a pixel value for a surface. + * + * This function maps the RGBA color value to the specified pixel format and + * returns the pixel value best approximating the given RGBA color value for + * the given pixel format. + * + * If the surface pixel format has no alpha component the alpha value will be + * ignored (as it will be in formats with a palette). + * + * If the surface has a palette, the index of the closest matching color in + * the palette will be returned. + * + * If the pixel format bpp (color depth) is less than 32-bpp then the unused + * upper bits of the return value can safely be ignored (e.g., with a 16-bpp + * format the return value can be assigned to a Uint16, and similarly a Uint8 + * for an 8-bpp format). + * + * \param surface the surface to use for the pixel format and palette. + * \param r the red component of the pixel in the range 0-255. + * \param g the green component of the pixel in the range 0-255. + * \param b the blue component of the pixel in the range 0-255. + * \param a the alpha component of the pixel in the range 0-255. + * \returns a pixel value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MapSurfaceRGB + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b, Uint8 a); + +/** + * Retrieves a single pixel from a surface. + * + * This function prioritizes correctness over speed: it is suitable for unit + * tests, but is not intended for use in a game engine. + * + * Like SDL_GetRGBA, this uses the entire 0..255 range when converting color + * components from pixel formats with less than 8 bits per RGB component. + * + * \param surface the surface to read. + * \param x the horizontal coordinate, 0 <= x < width. + * \param y the vertical coordinate, 0 <= y < height. + * \param r a pointer filled in with the red channel, 0-255, or NULL to ignore + * this channel. + * \param g a pointer filled in with the green channel, 0-255, or NULL to + * ignore this channel. + * \param b a pointer filled in with the blue channel, 0-255, or NULL to + * ignore this channel. + * \param a a pointer filled in with the alpha channel, 0-255, or NULL to + * ignore this channel. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); + +/** + * Retrieves a single pixel from a surface. + * + * This function prioritizes correctness over speed: it is suitable for unit + * tests, but is not intended for use in a game engine. + * + * \param surface the surface to read. + * \param x the horizontal coordinate, 0 <= x < width. + * \param y the vertical coordinate, 0 <= y < height. + * \param r a pointer filled in with the red channel, normally in the range + * 0-1, or NULL to ignore this channel. + * \param g a pointer filled in with the green channel, normally in the range + * 0-1, or NULL to ignore this channel. + * \param b a pointer filled in with the blue channel, normally in the range + * 0-1, or NULL to ignore this channel. + * \param a a pointer filled in with the alpha channel, normally in the range + * 0-1, or NULL to ignore this channel. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); + +/** + * Writes a single pixel to a surface. + * + * This function prioritizes correctness over speed: it is suitable for unit + * tests, but is not intended for use in a game engine. + * + * Like SDL_MapRGBA, this uses the entire 0..255 range when converting color + * components from pixel formats with less than 8 bits per RGB component. + * + * \param surface the surface to write. + * \param x the horizontal coordinate, 0 <= x < width. + * \param y the vertical coordinate, 0 <= y < height. + * \param r the red channel value, 0-255. + * \param g the green channel value, 0-255. + * \param b the blue channel value, 0-255. + * \param a the alpha channel value, 0-255. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); + +/** + * Writes a single pixel to a surface. + * + * This function prioritizes correctness over speed: it is suitable for unit + * tests, but is not intended for use in a game engine. + * + * \param surface the surface to write. + * \param x the horizontal coordinate, 0 <= x < width. + * \param y the vertical coordinate, 0 <= y < height. + * \param r the red channel value, normally in the range 0-1. + * \param g the green channel value, normally in the range 0-1. + * \param b the blue channel value, normally in the range 0-1. + * \param a the alpha channel value, normally in the range 0-1. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_surface_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_system.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_system.h new file mode 100644 index 0000000000..294089ff4a --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_system.h @@ -0,0 +1,818 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategorySystem + * + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. + */ + +#ifndef SDL_system_h_ +#define SDL_system_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + + +/* + * Platform specific functions for Windows + */ +#if defined(SDL_PLATFORM_WINDOWS) + +typedef struct tagMSG MSG; + +/** + * A callback to be used with SDL_SetWindowsMessageHook. + * + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. + * + * As this is processing a message directly from the Windows event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to + * SDL_SetWindowsMessageHook. + * \param msg a pointer to a Win32 event structure 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 + * Windows event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetWindowsMessageHook + * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP + */ +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); + +/** + * Set a callback for every Windows message, run before TranslateMessage(). + * + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. + * + * \param callback the SDL_WindowsMessageHook function to call. + * \param userdata a pointer to pass to every iteration of `callback`. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WindowsMessageHook + * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); + +#endif /* defined(SDL_PLATFORM_WINDOWS) */ + +#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) + +/** + * Get the D3D9 adapter index that matches the specified display. + * + * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and + * controls on which monitor a full screen application will appear. + * + * \param displayID the instance of the display to query. + * \returns the D3D9 adapter index on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); + +/** + * Get the DXGI Adapter and Output indices for the specified display. + * + * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and + * `EnumOutputs` respectively to get the objects required to create a DX10 or + * DX11 device and swap chain. + * + * \param displayID the instance of the display to query. + * \param adapterIndex a pointer to be filled in with the adapter index. + * \param outputIndex a pointer to be filled in with the output index. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); + +#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + + +/* + * 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.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * Set a callback for every X11 event. + * + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * \param callback the SDL_X11EventHook function to call. + * \param userdata a pointer to pass to every iteration of `callback`. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); + +/* Platform specific functions for Linux*/ +#ifdef SDL_PLATFORM_LINUX + +/** + * Sets the UNIX nice value for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID the Unix thread ID to change priority of. + * \param priority the new, Unix-specific, priority value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); + +/** + * Sets the priority (not nice level) and scheduling policy for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID the Unix thread ID to change priority of. + * \param sdlPriority the new SDL_ThreadPriority value. + * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, + * SCHED_OTHER, etc...). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); + +#endif /* SDL_PLATFORM_LINUX */ + +/* + * Platform specific functions for iOS + */ +#ifdef SDL_PLATFORM_IOS + +/** + * The prototype for an Apple iOS animation callback. + * + * This datatype is only useful on Apple iOS. + * + * After passing a function pointer of this type to + * SDL_SetiOSAnimationCallback, the system will call that function pointer at + * a regular interval. + * + * \param userdata what was passed as `callbackParam` to + * SDL_SetiOSAnimationCallback as `callbackParam`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetiOSAnimationCallback + */ +typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); + +/** + * Use this function to set the animation callback on Apple iOS. + * + * The function prototype for `callback` is: + * + * ```c + * void callback(void *callbackParam); + * ``` + * + * Where its parameter, `callbackParam`, is what was passed as `callbackParam` + * to SDL_SetiOSAnimationCallback(). + * + * This function is only available on Apple iOS. + * + * For more information see: + * + * https://wiki.libsdl.org/SDL3/README/ios + * + * Note that if you use the "main callbacks" instead of a standard C `main` + * function, you don't have to use this API, as SDL will manage this for you. + * + * Details on main callbacks are here: + * + * https://wiki.libsdl.org/SDL3/README/main-functions + * + * \param window the window for which the animation callback should be set. + * \param interval the number of frames after which **callback** will be + * called. + * \param callback the function to call for every frame. + * \param callbackParam a pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetiOSEventPump + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); + +/** + * Use this function to enable or disable the SDL event pump on Apple iOS. + * + * This function is only available on Apple iOS. + * + * \param enabled true to enable the event pump, false to disable it. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetiOSAnimationCallback + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); + +#endif /* SDL_PLATFORM_IOS */ + + +/* + * Platform specific functions for Android + */ +#ifdef SDL_PLATFORM_ANDROID + +/** + * Get the Android Java Native Interface Environment of the current thread. + * + * This is the JNIEnv one needs to access the Java virtual machine from native + * code, and is needed for many Android APIs to be usable from C. + * + * The prototype of the function in SDL's code actually declare a void* return + * type, even if the implementation returns a pointer to a JNIEnv. The + * rationale being that the SDL headers can avoid including jni.h. + * + * \returns a pointer to Java native interface object (JNIEnv) to which the + * current thread is attached, or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidActivity + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); + +/** + * Retrieve the Java instance of the Android activity class. + * + * The prototype of the function in SDL's code actually declares a void* + * return type, even if the implementation returns a jobject. The rationale + * being that the SDL headers can avoid including jni.h. + * + * The jobject returned by the function is a local reference and must be + * released by the caller. See the PushLocalFrame() and PopLocalFrame() or + * DeleteLocalRef() functions of the Java native interface: + * + * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html + * + * \returns the jobject representing the instance of the Activity class of the + * Android application, or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidJNIEnv + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); + +/** + * Query Android API level of the current device. + * + * - API level 35: Android 15 (VANILLA_ICE_CREAM) + * - API level 34: Android 14 (UPSIDE_DOWN_CAKE) + * - API level 33: Android 13 (TIRAMISU) + * - API level 32: Android 12L (S_V2) + * - API level 31: Android 12 (S) + * - API level 30: Android 11 (R) + * - API level 29: Android 10 (Q) + * - API level 28: Android 9 (P) + * - API level 27: Android 8.1 (O_MR1) + * - API level 26: Android 8.0 (O) + * - API level 25: Android 7.1 (N_MR1) + * - API level 24: Android 7.0 (N) + * - API level 23: Android 6.0 (M) + * - API level 22: Android 5.1 (LOLLIPOP_MR1) + * - API level 21: Android 5.0 (LOLLIPOP, L) + * - API level 20: Android 4.4W (KITKAT_WATCH) + * - API level 19: Android 4.4 (KITKAT) + * - API level 18: Android 4.3 (JELLY_BEAN_MR2) + * - API level 17: Android 4.2 (JELLY_BEAN_MR1) + * - API level 16: Android 4.1 (JELLY_BEAN) + * - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1) + * - API level 14: Android 4.0 (ICE_CREAM_SANDWICH) + * - API level 13: Android 3.2 (HONEYCOMB_MR2) + * - API level 12: Android 3.1 (HONEYCOMB_MR1) + * - API level 11: Android 3.0 (HONEYCOMB) + * - API level 10: Android 2.3.3 (GINGERBREAD_MR1) + * + * \returns the Android API level. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); + +/** + * Query if the application is running on a Chromebook. + * + * \returns true if this is a Chromebook, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); + +/** + * Query if the application is running on a Samsung DeX docking station. + * + * \returns true if this is a DeX docking station, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); + +/** + * Trigger the Android system back button behavior. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); + +/** + * 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.2.0. + */ +#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.2.0. + */ +#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 + +/** + * Get the path used for internal storage for this Android application. + * + * This path is unique to your application and cannot be written to by other + * applications. + * + * Your internal storage path is typically: + * `/data/data/your.app.package/files`. + * + * This is a C wrapper over `android.content.Context.getFilesDir()`: + * + * https://developer.android.com/reference/android/content/Context#getFilesDir() + * + * \returns the path used for internal storage or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); + +/** + * Get the current state of external storage for this Android application. + * + * The current state of external storage, a bitmask of these values: + * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`. + * + * If external storage is currently unavailable, this will return 0. + * + * \returns the current state of external storage, or 0 if external storage is + * currently unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidExternalStoragePath + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); + +/** + * Get the path used for external storage for this Android application. + * + * This path is unique to your application, but is public and can be written + * to by other applications. + * + * Your external storage path is typically: + * `/storage/sdcard0/Android/data/your.app.package/files`. + * + * This is a C wrapper over `android.content.Context.getExternalFilesDir()`: + * + * https://developer.android.com/reference/android/content/Context#getExternalFilesDir() + * + * \returns the path used for external storage for this application on success + * or NULL on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); + +/** + * Get the path used for caching data for this Android application. + * + * This path is unique to your application, but is public and can be written + * to by other applications. + * + * Your cache path is typically: `/data/data/your.app.package/cache/`. + * + * This is a C wrapper over `android.content.Context.getCacheDir()`: + * + * https://developer.android.com/reference/android/content/Context#getCacheDir() + * + * \returns the path used for caches for this application on success or NULL + * on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath + */ +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.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); + +/** + * Request permissions at runtime, asynchronously. + * + * You do not need to call this for built-in functionality of SDL; recording + * from a microphone or reading images from a camera, using standard SDL APIs, + * will manage permission requests for you. + * + * This function never blocks. Instead, the app-supplied callback will be + * called when a decision has been made. This callback may happen on a + * different thread, and possibly much later, as it might wait on a user to + * respond to a system dialog. If permission has already been granted for a + * specific entitlement, the callback will still fire, probably on the current + * thread and before this function returns. + * + * If the request submission fails, this function returns -1 and the callback + * will NOT be called, but this should only happen in catastrophic conditions, + * like memory running out. Normally there will be a yes or no to the request + * through the callback. + * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * + * \param permission the permission to request. + * \param cb the callback to trigger when the request has a response. + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported + * through the callback, not this return value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); + +/** + * Shows an Android toast notification. + * + * Toasts are a sort of lightweight notification that are unique to Android. + * + * https://developer.android.com/guide/topics/ui/notifiers/toasts + * + * Shows toast in UI thread. + * + * For the `gravity` parameter, choose a value from here, or -1 if you don't + * have a preference: + * + * https://developer.android.com/reference/android/view/Gravity + * + * \param message text message to be shown. + * \param duration 0=short, 1=long. + * \param gravity where the notification should appear on the screen. + * \param xoffset set this parameter only when gravity >=0. + * \param yoffset set this parameter only when gravity >=0. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); + +/** + * Send a user command to SDLActivity. + * + * Override "boolean onUnhandledMessage(Message msg)" to handle the message. + * + * \param command user command that must be greater or equal to 0x8000. + * \param param user parameter. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); + +#endif /* SDL_PLATFORM_ANDROID */ + +/** + * Query if the current device is a tablet. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a tablet, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + + +/* Functions used by iOS app delegates to notify SDL about state changes. */ + +/** + * Let iOS apps with external event handling report + * onApplicationWillTerminate. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); + +/** + * Let iOS apps with external event handling report + * onApplicationDidReceiveMemoryWarning. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); + +/** + * Let iOS apps with external event handling report + * onApplicationWillResignActive. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); + +/** + * Let iOS apps with external event handling report + * onApplicationDidEnterBackground. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); + +/** + * Let iOS apps with external event handling report + * onApplicationWillEnterForeground. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); + +/** + * Let iOS apps with external event handling report + * onApplicationDidBecomeActive. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); + +#ifdef SDL_PLATFORM_IOS + +/** + * Let iOS apps with external event handling report + * onApplicationDidChangeStatusBarOrientation. + * + * This functions allows iOS apps that have their own event handling to hook + * into SDL to generate SDL events. This maps directly to an iOS-specific + * event, but since it doesn't do anything iOS-specific internally, it is + * available on all platforms, in case it might be useful for some specific + * paradigm. Most apps do not need to use this directly; SDL's internal event + * code will handle all this for windows created by SDL_CreateWindow! + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); +#endif + +/* + * Functions used only by GDK + */ +#ifdef SDL_PLATFORM_GDK +typedef struct XTaskQueueObject *XTaskQueueHandle; +typedef struct XUser *XUserHandle; + +/** + * Gets a reference to the global async task queue handle for GDK, + * initializing if needed. + * + * Once you are done with the task queue, you should call + * XTaskQueueCloseHandle to reduce the reference count to avoid a resource + * leak. + * + * \param outTaskQueue a pointer to be filled in with task queue handle. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); + +/** + * Gets a reference to the default user handle for GDK. + * + * This is effectively a synchronous version of XUserAddAsync, which always + * prefers the default user and allows a sign-in UI. + * + * \param outUserHandle a pointer to be filled in with the default user + * handle. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); + +#endif + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_system_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test.h similarity index 72% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test.h index 78a7e623e4..8b285807c2 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test.h @@ -19,32 +19,28 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test.h - * +/** * Include file for SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ #ifndef SDL_test_h_ #define SDL_test_h_ -#include "SDL.h" -#include "SDL_test_assert.h" -#include "SDL_test_common.h" -#include "SDL_test_compare.h" -#include "SDL_test_crc32.h" -#include "SDL_test_font.h" -#include "SDL_test_fuzzer.h" -#include "SDL_test_harness.h" -#include "SDL_test_images.h" -#include "SDL_test_log.h" -#include "SDL_test_md5.h" -#include "SDL_test_memory.h" -#include "SDL_test_random.h" - -#include "begin_code.h" +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -62,8 +58,6 @@ extern "C" { #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_assert.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_assert.h similarity index 59% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_assert.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_assert.h index ff3b6b6bcd..c067608a59 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_assert.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_assert.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_assert.h - * - * Include file for SDL test framework. +/** + * Assertion functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,70 +34,65 @@ #ifndef SDL_test_assert_h_ #define SDL_test_assert_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif -/* - * \brief Fails the assert. - */ +/* Fails the assert. */ #define ASSERT_FAIL 0 -/* - * \brief Passes the assert. - */ +/* Passes the assert. */ #define ASSERT_PASS 1 /* - * \brief Assert that logs and break execution flow on failures. + * Assert that logs and break execution flow on failures. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertDescription Message to log with the assert describing it. */ -void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); +void SDLCALL SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); /* - * \brief Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. + * Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertDescription Message to log with the assert describing it. * * \returns the assertCondition so it can be used to externally to break execution flow if desired. */ -int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); +int SDLCALL SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); /* - * \brief Explicitly pass without checking an assertion condition. Updates assertion counter. + * Explicitly pass without checking an assertion condition. Updates assertion counter. * * \param assertDescription Message to log with the assert describing it. */ -void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); /* - * \brief Resets the assert summary counters to zero. + * Resets the assert summary counters to zero. */ -void SDLTest_ResetAssertSummary(void); +void SDLCALL SDLTest_ResetAssertSummary(void); /* - * \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. + * Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. */ -void SDLTest_LogAssertSummary(void); - +void SDLCALL SDLTest_LogAssertSummary(void); /* - * \brief Converts the current assert summary state to a test result. + * Converts the current assert summary state to a test result. * * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT */ -int SDLTest_AssertSummaryToTestResult(void); +int SDLCALL SDLTest_AssertSummaryToTestResult(void); #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_assert_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_common.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_common.h similarity index 52% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_common.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_common.h index 64b5f83e80..91efe8ac34 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_common.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_common.h @@ -19,25 +19,23 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_common.h - * - * Include file for SDL test framework. +/** + * Common functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ -/* Ported from original test\common.h file. */ +/* Ported from original test/common.h file. */ #ifndef SDL_test_common_h_ #define SDL_test_common_h_ -#include "SDL.h" +#include -#if defined(__PSP__) +#ifdef SDL_PLATFORM_PSP #define DEFAULT_WINDOW_WIDTH 480 #define DEFAULT_WINDOW_HEIGHT 272 -#elif defined(__VITA__) +#elif defined(SDL_PLATFORM_VITA) #define DEFAULT_WINDOW_WIDTH 960 #define DEFAULT_WINDOW_HEIGHT 544 #else @@ -45,6 +43,7 @@ #define DEFAULT_WINDOW_HEIGHT 480 #endif +typedef Uint32 SDLTest_VerboseFlags; #define VERBOSE_VIDEO 0x00000001 #define VERBOSE_MODES 0x00000002 #define VERBOSE_RENDER 0x00000004 @@ -52,20 +51,42 @@ #define VERBOSE_AUDIO 0x00000010 #define VERBOSE_MOTION 0x00000020 +/* !< Function pointer parsing one argument at argv[index], returning the number of parsed arguments, + * or a negative value when the argument is invalid */ +typedef int (SDLCALL *SDLTest_ParseArgumentsFp)(void *data, char **argv, int index); + +/* !< Finalize the argument parser. */ +typedef void (SDLCALL *SDLTest_FinalizeArgumentParserFp)(void *arg); + +typedef struct SDLTest_ArgumentParser +{ + /* !< Parse an argument. */ + SDLTest_ParseArgumentsFp parse_arguments; + /* !< Finalize this argument parser. Called once before parsing the first argument. */ + SDLTest_FinalizeArgumentParserFp finalize; + /* !< Null-terminated array of arguments. Printed when running with --help. */ + const char **usage; + /* !< User data, passed to all callbacks. */ + void *data; + /* !< Next argument parser. */ + struct SDLTest_ArgumentParser *next; +} SDLTest_ArgumentParser; + typedef struct { /* SDL init flags */ char **argv; - Uint32 flags; - Uint32 verbose; + SDL_InitFlags flags; + SDLTest_VerboseFlags verbose; /* Video info */ const char *videodriver; - int display; + int display_index; + SDL_DisplayID displayID; const char *window_title; const char *window_icon; - Uint32 window_flags; - SDL_bool flash_on_focus_loss; + SDL_WindowFlags window_flags; + bool flash_on_focus_loss; int window_x; int window_y; int window_w; @@ -74,24 +95,35 @@ typedef struct int window_minH; int window_maxW; int window_maxH; + float window_min_aspect; + float window_max_aspect; int logical_w; int logical_h; + bool auto_scale_content; + SDL_RendererLogicalPresentation logical_presentation; float scale; int depth; - int refresh_rate; + float refresh_rate; + bool fill_usable_bounds; + bool fullscreen_exclusive; + SDL_DisplayMode fullscreen_mode; int num_windows; SDL_Window **windows; + const char *gpudriver; /* Renderer info */ const char *renderdriver; - Uint32 render_flags; - SDL_bool skip_renderer; + int render_vsync; + bool skip_renderer; SDL_Renderer **renderers; SDL_Texture **targets; /* Audio info */ const char *audiodriver; - SDL_AudioSpec audiospec; + SDL_AudioFormat audio_format; + int audio_channels; + int audio_freq; + SDL_AudioDeviceID audio_id; /* GL settings */ int gl_red_size; @@ -107,6 +139,7 @@ typedef struct int gl_accum_blue_size; int gl_accum_alpha_size; int gl_stereo; + int gl_release_behavior; int gl_multisamplebuffers; int gl_multisamplesamples; int gl_retained_backing; @@ -116,12 +149,19 @@ typedef struct int gl_debug; int gl_profile_mask; - /* Additional fields added in 2.0.18 */ + /* Mouse info */ SDL_Rect confine; + bool hide_cursor; + + /* Options info */ + SDLTest_ArgumentParser common_argparser; + SDLTest_ArgumentParser video_argparser; + SDLTest_ArgumentParser audio_argparser; + SDLTest_ArgumentParser *argparser; } SDLTest_CommonState; -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -129,29 +169,38 @@ extern "C" { /* Function prototypes */ -/* - * \brief Parse command line parameters and create common state. +/** + * Parse command line parameters and create common state. * * \param argv Array of command line parameters * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO) * * \returns a newly allocated common state object. */ -SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags); +SDLTest_CommonState * SDLCALL SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags); -/* - * \brief Process one common argument. +/** + * Free the common state object. + * + * You should call SDL_Quit() before calling this function. + * + * \param state The common state object to destroy + */ +void SDLCALL SDLTest_CommonDestroyState(SDLTest_CommonState *state); + +/** + * Process one common argument. * * \param state The common state describing the test window to create. * \param index The index of the argument to process in argv[]. * * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error. */ -int SDLTest_CommonArg(SDLTest_CommonState * state, int index); +int SDLCALL SDLTest_CommonArg(SDLTest_CommonState *state, int index); -/* - * \brief Logs command line usage info. +/** + * Logs command line usage info. * * This logs the appropriate command line options for the subsystems in use * plus other common options, and then any application-specific options. @@ -162,75 +211,79 @@ int SDLTest_CommonArg(SDLTest_CommonState * state, int index); * \param argv0 argv[0], as passed to main/SDL_main. * \param options an array of strings for application specific options. The last element of the array should be NULL. */ -void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, const char **options); +void SDLCALL SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options); -/* - * \brief Returns common usage information - * - * You should (probably) be using SDLTest_CommonLogUsage() instead, but this - * function remains for binary compatibility. Strings returned from this - * function are valid until SDLTest_CommonQuit() is called, in which case - * those strings' memory is freed and can no longer be used. +/** + * Open test window. * * \param state The common state describing the test window to create. - * \returns a string with usage information + * + * \returns true if initialization succeeded, false otherwise */ -const char *SDLTest_CommonUsage(SDLTest_CommonState * state); +bool SDLCALL SDLTest_CommonInit(SDLTest_CommonState *state); -/* - * \brief Open test window. +/** + * Easy argument handling when test app doesn't need any custom args. * * \param state The common state describing the test window to create. + * \param argc argc, as supplied to SDL_main + * \param argv argv, as supplied to SDL_main * - * \returns SDL_TRUE if initialization succeeded, false otherwise + * \returns false if app should quit, true otherwise. */ -SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); +bool SDLCALL SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv); -/* - * \brief Easy argument handling when test app doesn't need any custom args. +/** + * Print the details of an event. * - * \param state The common state describing the test window to create. - * \param argc argc, as supplied to SDL_main - * \param argv argv, as supplied to SDL_main + * This is automatically called by SDLTest_CommonEvent() as needed. * - * \returns SDL_FALSE if app should quit, true otherwise. + * \param event The event to print. */ -SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv); +void SDLCALL SDLTest_PrintEvent(const SDL_Event *event); -/* - * \brief Common event handler for test windows. +/** + * Common event handler for test windows if you use a standard SDL_main. * * \param state The common state used to create test window. * \param event The event to handle. * \param done Flag indicating we are done. + */ +void SDLCALL SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done); + +/** + * Common event handler for test windows if you use SDL_AppEvent. * + * This does _not_ free anything in `event`. + * + * \param state The common state used to create test window. + * \param event The event to handle. + * \returns Value suitable for returning from SDL_AppEvent(). */ -void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done); +SDL_AppResult SDLCALL SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event); -/* - * \brief Close test window. +/** + * Close test window. * * \param state The common state used to create test window. * */ -void SDLTest_CommonQuit(SDLTest_CommonState * state); +void SDLCALL SDLTest_CommonQuit(SDLTest_CommonState *state); -/* - * \brief Draws various window information (position, size, etc.) to the renderer. +/** + * Draws various window information (position, size, etc.) to the renderer. * * \param renderer The renderer to draw to. * \param window The window whose information should be displayed. * \param usedHeight Returns the height used, so the caller can draw more below. * */ -void SDLTest_CommonDrawWindowInfo(SDL_Renderer * renderer, SDL_Window * window, int * usedHeight); +void SDLCALL SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_common_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_compare.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_compare.h similarity index 64% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_compare.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_compare.h index 3fcb935970..7ff247793a 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_compare.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_compare.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_compare.h - * - * Include file for SDL test framework. +/** + * Comparison function of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,18 +34,16 @@ #ifndef SDL_test_compare_h_ #define SDL_test_compare_h_ -#include "SDL.h" - -#include "SDL_test_images.h" +#include -#include "begin_code.h" +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif -/* - * \brief Compares a surface and with reference image data for equality +/** + * Compares a surface and with reference image data for equality * * \param surface Surface used in comparison * \param referenceSurface Test Surface used in comparison @@ -55,15 +51,26 @@ extern "C" { * * \returns 0 if comparison succeeded, >0 (=number of pixels for which the comparison failed) if comparison failed, -1 if any of the surfaces were NULL, -2 if the surface sizes differ. */ -int SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, int allowable_error); +int SDLCALL SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, int allowable_error); +/** + * Compares 2 memory blocks for equality + * + * \param actual Memory used in comparison, displayed on the left + * \param size_actual Size of actual in bytes + * \param reference Reference memory, displayed on the right + * \param size_reference Size of reference in bytes + * + * \returns 0 if the left and right memory block are equal, non-zero if they are non-equal. + * + * \since This function is available since SDL 3.2.0. + */ +int SDLCALL SDLTest_CompareMemory(const void *actual, size_t size_actual, const void *reference, size_t size_reference); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_compare_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_crc32.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_crc32.h similarity index 66% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_crc32.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_crc32.h index 1dbeef2768..94fe1a345a 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_crc32.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_crc32.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_crc32.h - * - * Include file for SDL test framework. +/** + * CRC32 functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,13 +34,14 @@ #ifndef SDL_test_crc32_h_ #define SDL_test_crc32_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* ------------ Definitions --------- */ /* Definition shared by all CRC routines */ @@ -63,62 +62,60 @@ extern "C" { /* * Data structure for CRC32 (checksum) computation */ - typedef struct { + typedef struct SDLTest_Crc32Context { CrcUint32 crc32_table[256]; /* CRC table */ } SDLTest_Crc32Context; /* ---------- Function Prototypes ------------- */ /* - * \brief Initialize the CRC context + * Initialize the CRC context * * Note: The function initializes the crc table required for all crc calculations. * * \param crcContext pointer to context variable * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ - int SDLTest_Crc32Init(SDLTest_Crc32Context * crcContext); - +bool SDLCALL SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext); /* - * \brief calculate a crc32 from a data block + * calculate a crc32 from a data block * * \param crcContext pointer to context variable * \param inBuf input buffer to checksum * \param inLen length of input buffer * \param crc32 pointer to Uint32 to store the final CRC into * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ -int SDLTest_Crc32Calc(SDLTest_Crc32Context * crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); /* Same routine broken down into three steps */ -int SDLTest_Crc32CalcStart(SDLTest_Crc32Context * crcContext, CrcUint32 *crc32); -int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context * crcContext, CrcUint32 *crc32); -int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context * crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); - +bool SDLCALL SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); /* - * \brief clean up CRC context + * clean up CRC context * * \param crcContext pointer to context variable * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ -int SDLTest_Crc32Done(SDLTest_Crc32Context * crcContext); - +bool SDLCALL SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_crc32_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_font.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_font.h similarity index 62% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_font.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_font.h index 0eade92394..fb40794972 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_font.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_font.h @@ -20,17 +20,19 @@ */ /* - * \file SDL_test_font.h + * Font related functions of SDL test framework. * - * Include file for SDL test framework. - * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ #ifndef SDL_test_font_h_ #define SDL_test_font_h_ -#include "begin_code.h" +#include +#include +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -38,23 +40,24 @@ extern "C" { /* Function prototypes */ -#define FONT_CHARACTER_SIZE 8 +extern int FONT_CHARACTER_SIZE; + #define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2) /* - * \brief Draw a string in the currently set font. + * Draw a string in the currently set font. * * \param renderer The renderer to draw on. * \param x The X coordinate of the upper left corner of the character. * \param y The Y coordinate of the upper left corner of the character. * \param c The character to draw. * - * \returns 0 on success, -1 on failure. + * \returns true on success, false on failure. */ -int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c); +bool SDLCALL SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); /* - * \brief Draw a UTF-8 string in the currently set font. + * Draw a UTF-8 string in the currently set font. * * The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets. * @@ -63,23 +66,23 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c); * \param y The Y coordinate of the upper left corner of the string. * \param s The string to draw. * - * \returns 0 on success, -1 on failure. + * \returns true on success, false on failure. */ -int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s); +bool SDLCALL SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s); /* - * \brief Data used for multi-line text output + * Data used for multi-line text output */ typedef struct SDLTest_TextWindow { - SDL_Rect rect; + SDL_FRect rect; int current; int numlines; char **lines; } SDLTest_TextWindow; /* - * \brief Create a multi-line text output window + * Create a multi-line text output window * * \param x The X coordinate of the upper left corner of the window. * \param y The Y coordinate of the upper left corner of the window. @@ -88,24 +91,24 @@ typedef struct SDLTest_TextWindow * * \returns the new window, or NULL on failure. * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h); +SDLTest_TextWindow * SDLCALL SDLTest_TextWindowCreate(float x, float y, float w, float h); /* - * \brief Display a multi-line text output window + * Display a multi-line text output window * * This function should be called every frame to display the text * * \param textwin The text output window * \param renderer The renderer to use for display * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); +void SDLCALL SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); /* - * \brief Add text to a multi-line text output window + * Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a * new line of text. The backspace character deletes the last character or, if the @@ -115,12 +118,12 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render * \param fmt A printf() style format string * \param ... additional parameters matching % tokens in the `fmt` string, if any * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); +void SDLCALL SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); /* - * \brief Add text to a multi-line text output window + * Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a * new line of text. The backspace character deletes the last character or, if the @@ -130,39 +133,37 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST * \param text The text to add to the window * \param len The length, in bytes, of the text to add to the window * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); +void SDLCALL SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); /* - * \brief Clear the text in a multi-line text output window + * Clear the text in a multi-line text output window * * \param textwin The text output window * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); +void SDLCALL SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); /* - * \brief Free the storage associated with a multi-line text output window + * Free the storage associated with a multi-line text output window * * \param textwin The text output window * - * \since This function is available since SDL 2.24.0 + * \since This function is available since SDL 3.2.0. */ -void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); +void SDLCALL SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); /* - * \brief Cleanup textures used by font drawing functions. + * Cleanup textures used by font drawing functions. */ -void SDLTest_CleanupTextDrawing(void); +void SDLCALL SDLTest_CleanupTextDrawing(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_font_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_fuzzer.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_fuzzer.h similarity index 68% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_fuzzer.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_fuzzer.h index c6978ac810..caf11f2528 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_fuzzer.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_fuzzer.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_fuzzer.h - * - * Include file for SDL test framework. +/** + * Fuzzer functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,116 +34,110 @@ #ifndef SDL_test_fuzzer_h_ #define SDL_test_fuzzer_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* Based on GSOC code by Markus Kauppila */ - -/* - * \file +/** * Note: The fuzzer implementation uses a static instance of random context * internally which makes it thread-UNsafe. */ -/* +/** * Initializes the fuzzer for a test * * \param execKey Execution "Key" that initializes the random number generator uniquely for the test. * */ -void SDLTest_FuzzerInit(Uint64 execKey); - +void SDLCALL SDLTest_FuzzerInit(Uint64 execKey); -/* +/** * Returns a random Uint8 * * \returns a generated integer */ -Uint8 SDLTest_RandomUint8(void); +Uint8 SDLCALL SDLTest_RandomUint8(void); -/* +/** * Returns a random Sint8 * * \returns a generated signed integer */ -Sint8 SDLTest_RandomSint8(void); - +Sint8 SDLCALL SDLTest_RandomSint8(void); -/* +/** * Returns a random Uint16 * * \returns a generated integer */ -Uint16 SDLTest_RandomUint16(void); +Uint16 SDLCALL SDLTest_RandomUint16(void); -/* +/** * Returns a random Sint16 * * \returns a generated signed integer */ -Sint16 SDLTest_RandomSint16(void); - +Sint16 SDLCALL SDLTest_RandomSint16(void); -/* +/** * Returns a random integer * * \returns a generated integer */ -Sint32 SDLTest_RandomSint32(void); - +Sint32 SDLCALL SDLTest_RandomSint32(void); -/* +/** * Returns a random positive integer * * \returns a generated integer */ -Uint32 SDLTest_RandomUint32(void); +Uint32 SDLCALL SDLTest_RandomUint32(void); -/* +/** * Returns random Uint64. * * \returns a generated integer */ Uint64 SDLTest_RandomUint64(void); - -/* +/** * Returns random Sint64. * * \returns a generated signed integer */ -Sint64 SDLTest_RandomSint64(void); +Sint64 SDLCALL SDLTest_RandomSint64(void); -/* +/** * \returns a random float in range [0.0 - 1.0] */ -float SDLTest_RandomUnitFloat(void); +float SDLCALL SDLTest_RandomUnitFloat(void); -/* +/** * \returns a random double in range [0.0 - 1.0] */ -double SDLTest_RandomUnitDouble(void); +double SDLCALL SDLTest_RandomUnitDouble(void); -/* +/** * \returns a random float. * */ -float SDLTest_RandomFloat(void); +float SDLCALL SDLTest_RandomFloat(void); -/* +/** * \returns a random double. * */ -double SDLTest_RandomDouble(void); +double SDLCALL SDLTest_RandomDouble(void); -/* +/** * Returns a random boundary value for Uint8 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -153,10 +145,10 @@ double SDLTest_RandomDouble(void); * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint8BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint8BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint8BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint8BoundaryValue(0, 255, SDL_FALSE) returns 0 (error set) + * RandomUint8BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint8BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint8BoundaryValue(0, 99, false) returns 100 + * RandomUint8BoundaryValue(0, 255, false) returns 0 (error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -164,9 +156,9 @@ double SDLTest_RandomDouble(void); * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain); +Uint8 SDLCALL SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Uint16 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -174,10 +166,10 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint16BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint16BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint16BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint16BoundaryValue(0, 0xFFFF, SDL_FALSE) returns 0 (error set) + * RandomUint16BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint16BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint16BoundaryValue(0, 99, false) returns 100 + * RandomUint16BoundaryValue(0, 0xFFFF, false) returns 0 (error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -185,9 +177,9 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain); +Uint16 SDLCALL SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Uint32 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -195,10 +187,10 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint32BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint32BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint32BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint32BoundaryValue(0, 0xFFFFFFFF, SDL_FALSE) returns 0 (with error set) + * RandomUint32BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint32BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint32BoundaryValue(0, 99, false) returns 100 + * RandomUint32BoundaryValue(0, 0xFFFFFFFF, false) returns 0 (with error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -206,9 +198,9 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain); +Uint32 SDLCALL SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Uint64 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -216,10 +208,10 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint64BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint64BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint64BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, SDL_FALSE) returns 0 (with error set) + * RandomUint64BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint64BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint64BoundaryValue(0, 99, false) returns 100 + * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, false) returns 0 (with error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -227,9 +219,9 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain); +Uint64 SDLCALL SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Sint8 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -237,10 +229,10 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint8BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint8BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint8BoundaryValue(SINT8_MIN, 99, SDL_FALSE) returns 100 - * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, SDL_FALSE) returns SINT8_MIN (== error value) with error set + * RandomSint8BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint8BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint8BoundaryValue(SINT8_MIN, 99, false) returns 100 + * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, false) returns SINT8_MIN (== error value) with error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -248,10 +240,9 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT8_MIN with error set */ -Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain); - +Sint8 SDLCALL SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Sint16 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -259,10 +250,10 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint16BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint16BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint16BoundaryValue(SINT16_MIN, 99, SDL_FALSE) returns 100 - * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, SDL_FALSE) returns SINT16_MIN (== error value) with error set + * RandomSint16BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint16BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint16BoundaryValue(SINT16_MIN, 99, false) returns 100 + * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, false) returns SINT16_MIN (== error value) with error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -270,9 +261,9 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo * * \returns a random boundary value for the given range and domain or SINT16_MIN with error set */ -Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain); +Sint16 SDLCALL SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Sint32 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -280,10 +271,10 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint32BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint32BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint32BoundaryValue(SINT32_MIN, 99, SDL_FALSE) returns 100 - * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, SDL_FALSE) returns SINT32_MIN (== error value) + * RandomSint32BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint32BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint32BoundaryValue(SINT32_MIN, 99, false) returns 100 + * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, false) returns SINT32_MIN (== error value) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -291,9 +282,9 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT32_MIN with error set */ -Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain); +Sint32 SDLCALL SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, bool validDomain); -/* +/** * Returns a random boundary value for Sint64 within the given boundaries. * Boundaries are inclusive, see the usage examples below. If validDomain * is true, the function will only return valid boundaries, otherwise non-valid @@ -301,10 +292,10 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint64BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint64BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint64BoundaryValue(SINT64_MIN, 99, SDL_FALSE) returns 100 - * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, SDL_FALSE) returns SINT64_MIN (== error value) and error set + * RandomSint64BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint64BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint64BoundaryValue(SINT64_MIN, 99, false) returns 100 + * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, false) returns SINT64_MIN (== error value) and error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -312,10 +303,9 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT64_MIN with error set */ -Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain); +Sint64 SDLCALL SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, bool validDomain); - -/* +/** * Returns integer in range [min, max] (inclusive). * Min and max values can be negative values. * If Max in smaller than min, then the values are swapped. @@ -326,10 +316,9 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL * * \returns a generated random integer in range */ -Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); - +Sint32 SDLCALL SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); -/* +/** * Generates random null-terminated string. The minimum length for * the string is 1 character, maximum length for the string is 255 * characters and it can contain ASCII characters from 32 to 126. @@ -338,10 +327,9 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); * * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated. */ -char * SDLTest_RandomAsciiString(void); - +char * SDLCALL SDLTest_RandomAsciiString(void); -/* +/** * Generates random null-terminated string. The maximum length for * the string is defined by the maxLength parameter. * String can contain ASCII characters from 32 to 126. @@ -352,10 +340,9 @@ char * SDLTest_RandomAsciiString(void); * * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated. */ -char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); +char * SDLCALL SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); - -/* +/** * Generates random null-terminated string. The length for * the string is defined by the size parameter. * String can contain ASCII characters from 32 to 126. @@ -366,22 +353,19 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); * * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated. */ -char * SDLTest_RandomAsciiStringOfSize(int size); - +char * SDLCALL SDLTest_RandomAsciiStringOfSize(int size); -/* +/** * Get the invocation count for the fuzzer since last ...FuzzerInit. * * \returns the invocation count. */ -int SDLTest_GetFuzzerInvocationCount(void); +int SDLCALL SDLTest_GetFuzzerInvocationCount(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_fuzzer_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_harness.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_harness.h similarity index 61% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_harness.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_harness.h index cfd62e8401..5d4963e779 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_harness.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_harness.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_harness.h - * - * Include file for SDL test framework. +/** + * Test suite related functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,13 +34,15 @@ #ifndef SDL_test_h_arness_h #define SDL_test_h_arness_h -#include "begin_code.h" +#include +#include /* SDLTest_CommonState */ + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* ! Definitions for test case structures */ #define TEST_ENABLED 1 #define TEST_DISABLED 0 @@ -61,13 +61,13 @@ extern "C" { #define TEST_RESULT_SETUP_FAILURE 4 /* !< Function pointer to a test case setup function (run before every test) */ -typedef void (*SDLTest_TestCaseSetUpFp)(void *arg); +typedef void (SDLCALL *SDLTest_TestCaseSetUpFp)(void **arg); /* !< Function pointer to a test case function */ -typedef int (*SDLTest_TestCaseFp)(void *arg); +typedef int (SDLCALL *SDLTest_TestCaseFp)(void *arg); /* !< Function pointer to a test case teardown function (run after every test) */ -typedef void (*SDLTest_TestCaseTearDownFp)(void *arg); +typedef void (SDLCALL *SDLTest_TestCaseTearDownFp)(void *arg); /* * Holds information about a single test case. @@ -99,36 +99,53 @@ typedef struct SDLTest_TestSuiteReference { /* - * \brief Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z). - * - * Note: The returned string needs to be deallocated by the caller. + * Generates a random run seed string for the harness. The generated seed + * will contain alphanumeric characters (0-9A-Z). * - * \param length The length of the seed string to generate + * \param buffer Buffer in which to generate the random seed. Must have a capacity of at least length + 1 characters. + * \param length Number of alphanumeric characters to write to buffer, must be >0 * - * \returns the generated seed string + * \returns A null-terminated seed string and equal to the in put buffer on success, NULL on failure */ -char *SDLTest_GenerateRunSeed(const int length); +char * SDLCALL SDLTest_GenerateRunSeed(char *buffer, int length); /* - * \brief Execute a test suite using the given run seed and execution key. + * Holds information about the execution of test suites. + * */ +typedef struct SDLTest_TestSuiteRunner SDLTest_TestSuiteRunner; + +/* + * Create a new test suite runner, that will execute the given test suites. + * It will register the harness cli arguments to the common SDL state. * - * \param testSuites Suites containing the test case. - * \param userRunSeed Custom run seed provided by user, or NULL to autogenerate one. - * \param userExecKey Custom execution key provided by user, or 0 to autogenerate one. - * \param filter Filter specification. NULL disables. Case sensitive. - * \param testIterations Number of iterations to run each test case. + * \param state Common SDL state on which to register CLI arguments. + * \param testSuites NULL-terminated test suites containing test cases. * * \returns the test run result: 0 when all tests passed, 1 if any tests failed. */ -int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations); +SDLTest_TestSuiteRunner * SDLCALL SDLTest_CreateTestSuiteRunner(SDLTest_CommonState *state, SDLTest_TestSuiteReference *testSuites[]); +/* + * Destroy a test suite runner. + * It will unregister the harness cli arguments to the common SDL state. + * + * \param runner The runner that should be destroyed. + */ +void SDLCALL SDLTest_DestroyTestSuiteRunner(SDLTest_TestSuiteRunner *runner); + +/* + * Execute a test suite, using the configured run seed, execution key, filter, etc. + * + * \param runner The runner that should be executed. + * + * \returns the test run result: 0 when all tests passed, 1 if any tests failed. + */ +int SDLCALL SDLTest_ExecuteTestSuiteRunner(SDLTest_TestSuiteRunner *runner); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_h_arness_h */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_log.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_log.h similarity index 58% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_log.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_log.h index 6f7f66145b..0d48044a0c 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_log.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_log.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_log.h - * - * Include file for SDL test framework. +/** + * Logging related functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -36,32 +34,42 @@ #ifndef SDL_test_log_h_ #define SDL_test_log_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif -/* - * \brief Prints given message with a timestamp in the TEST category and INFO priority. +/** + * Prints given message with a timestamp in the TEST category and INFO priority. * * \param fmt Message to be logged */ -void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); -/* - * \brief Prints given message with a timestamp in the TEST category and the ERROR priority. +/** + * Prints given prefix and buffer. + * Non-printible characters in the raw data are substituted by printible alternatives. + * + * \param prefix Prefix message. + * \param buffer Raw data to be escaped. + * \param size Number of bytes in buffer. + */ +void SDLCALL SDLTest_LogEscapedString(const char *prefix, const void *buffer, size_t size); + +/** + * Prints given message with a timestamp in the TEST category and the ERROR priority. * * \param fmt Message to be logged */ -void SDLTest_LogError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_LogError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_log_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_md5.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_md5.h similarity index 82% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_md5.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_md5.h index edd79451c7..e9d96398a3 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_md5.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_md5.h @@ -19,12 +19,10 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_md5.h - * - * Include file for SDL test framework. +/** + * MD5 related functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ /* @@ -56,7 +54,9 @@ #ifndef SDL_test_md5_h_ #define SDL_test_md5_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { @@ -65,20 +65,20 @@ extern "C" { /* ------------ Definitions --------- */ /* typedef a 32-bit type */ - typedef unsigned long int MD5UINT4; +typedef Uint32 MD5UINT4; /* Data structure for MD5 (Message-Digest) computation */ - typedef struct { - MD5UINT4 i[2]; /* number of _bits_ handled mod 2^64 */ - MD5UINT4 buf[4]; /* scratch buffer */ - unsigned char in[64]; /* input buffer */ +typedef struct SDLTest_Md5Context { + MD5UINT4 i[2]; /* number of _bits_ handled mod 2^64 */ + MD5UINT4 buf[4]; /* scratch buffer */ + unsigned char in[64]; /* input buffer */ unsigned char digest[16]; /* actual digest after Md5Final call */ - } SDLTest_Md5Context; +} SDLTest_Md5Context; /* ---------- Function Prototypes ------------- */ -/* - * \brief initialize the context +/** + * initialize the context * * \param mdContext pointer to context variable * @@ -86,11 +86,10 @@ extern "C" { * mdContext. Call before each new use of the context - * all fields are set to zero. */ - void SDLTest_Md5Init(SDLTest_Md5Context * mdContext); +void SDLCALL SDLTest_Md5Init(SDLTest_Md5Context *mdContext); - -/* - * \brief update digest from variable length data +/** + * update digest from variable length data * * \param mdContext pointer to context variable * \param inBuf pointer to data array/string @@ -99,31 +98,25 @@ extern "C" { * Note: The function updates the message-digest context to account * for the presence of each of the characters inBuf[0..inLen-1] * in the message whose digest is being computed. -*/ - - void SDLTest_Md5Update(SDLTest_Md5Context * mdContext, unsigned char *inBuf, + */ +void SDLCALL SDLTest_Md5Update(SDLTest_Md5Context *mdContext, unsigned char *inBuf, unsigned int inLen); - -/* - * \brief complete digest computation +/** + * complete digest computation * * \param mdContext pointer to context variable * * Note: The function terminates the message-digest computation and * ends with the desired message digest in mdContext.digest[0..15]. * Always call before using the digest[] variable. -*/ - - void SDLTest_Md5Final(SDLTest_Md5Context * mdContext); - + */ +void SDLCALL SDLTest_Md5Final(SDLTest_Md5Context *mdContext); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_md5_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_test_memory.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_memory.h similarity index 70% rename from code/thirdparty/SDL2-2.32.8/include/SDL_test_memory.h rename to code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_memory.h index e789fa802a..1bd9466743 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_test_memory.h +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_test_memory.h @@ -19,45 +19,48 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_memory.h - * - * Include file for SDL test framework. +/** + * Memory tracking related functions of SDL test framework. * - * This code is a part of the SDL2_test library, not the main SDL library. + * This code is a part of the SDL test library, not the main SDL library. */ #ifndef SDL_test_memory_h_ #define SDL_test_memory_h_ -#include "begin_code.h" +#include + +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - -/* - * \brief Start tracking SDL memory allocations - * +/** + * Start tracking SDL memory allocations + * * \note This should be called before any other SDL functions for complete tracking coverage */ -int SDLTest_TrackAllocations(void); +void SDLCALL SDLTest_TrackAllocations(void); -/* - * \brief Print a log of any outstanding allocations +/** + * Fill allocations with random data * - * \note This can be called after SDL_Quit() + * \note This implicitly calls SDLTest_TrackAllocations() */ -void SDLTest_LogAllocations(void); +void SDLCALL SDLTest_RandFillAllocations(void); +/** + * Print a log of any outstanding allocations + * + * \note This can be called after SDL_Quit() + */ +void SDLCALL SDLTest_LogAllocations(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus } #endif -#include "close_code.h" +#include #endif /* SDL_test_memory_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_thread.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_thread.h new file mode 100644 index 0000000000..e981b54293 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_thread.h @@ -0,0 +1,578 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#ifndef SDL_thread_h_ +#define SDL_thread_h_ + +/** + * # CategoryThread + * + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. + */ + +#include +#include +#include + +/* Thread synchronization primitives */ +#include + +#if defined(SDL_PLATFORM_WINDOWS) +#include /* _beginthreadex() and _endthreadex() */ +#endif + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The SDL thread object. + * + * These are opaque data. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ +typedef struct SDL_Thread SDL_Thread; + +/** + * A unique numeric ID that identifies a thread. + * + * These are different from SDL_Thread objects, which are generally what an + * application will operate on, but having a way to uniquely identify a thread + * can be useful at times. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetThreadID + * \sa SDL_GetCurrentThreadID + */ +typedef Uint64 SDL_ThreadID; + +/** + * Thread local storage ID. + * + * 0 is the invalid ID. An app can create these and then set data for these + * IDs that is unique to each thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetTLS + * \sa SDL_SetTLS + */ +typedef SDL_AtomicInt SDL_TLSID; + +/** + * The SDL thread priority. + * + * SDL will make system changes as necessary in order to apply the thread + * priority. Code which attempts to control thread state related to priority + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_ThreadPriority { + SDL_THREAD_PRIORITY_LOW, + SDL_THREAD_PRIORITY_NORMAL, + SDL_THREAD_PRIORITY_HIGH, + SDL_THREAD_PRIORITY_TIME_CRITICAL +} SDL_ThreadPriority; + +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + +/** + * The function passed to SDL_CreateThread() as the new thread's entry point. + * + * \param data what was passed as `data` to SDL_CreateThread(). + * \returns a value that can be reported through SDL_WaitThread(). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef int (SDLCALL *SDL_ThreadFunction) (void *data); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/* + * Note that these aren't the correct function signatures in this block, but + * this is what the API reference manual should look like for all intents and + * purposes. + * + * Technical details, not for the wiki (hello, header readers!)... + * + * On Windows (and maybe other platforms), a program might use a different + * C runtime than its libraries. Or, in SDL's case, it might use a C runtime + * while SDL uses none at all. + * + * C runtimes expect to initialize thread-specific details when a new thread + * is created, but to do this in SDL_CreateThread would require SDL to know + * intimate details about the caller's C runtime, which is not possible. + * + * So SDL_CreateThread has two extra parameters, which are + * hidden at compile time by macros: the C runtime's `_beginthreadex` and + * `_endthreadex` entry points. If these are not NULL, they are used to spin + * and terminate the new thread; otherwise the standard Win32 `CreateThread` + * function is used. When `SDL_CreateThread` is called from a compiler that + * needs this C runtime thread init function, macros insert the appropriate + * function pointers for SDL_CreateThread's caller (which might be a different + * compiler with a different runtime in different calls to SDL_CreateThread!). + * + * SDL_BeginThreadFunction defaults to `_beginthreadex` on Windows (and NULL + * everywhere else), but apps that have extremely specific special needs can + * define this to something else and the SDL headers will use it, passing the + * app-defined value to SDL_CreateThread calls. Redefine this with caution! + * + * Platforms that don't need _beginthread stuff (most everything) will fail + * SDL_CreateThread with an error if these pointers _aren't_ NULL. + * + * Unless you are doing something extremely complicated, like perhaps a + * language binding, **you should never deal with this directly**. Let SDL's + * macros handle this platform-specific detail transparently! + */ + +/** + * Create a new thread with a default stack size. + * + * This is a convenience function, equivalent to calling + * SDL_CreateThreadWithProperties with the following properties set: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: `fn` + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: `name` + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: `data` + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param fn the SDL_ThreadFunction function to call in the new thread. + * \param name the name of the thread. + * \param data a pointer that is passed to `fn`. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThreadWithProperties + * \sa SDL_WaitThread + */ +extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); + +/** + * Create a new thread with with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: an SDL_ThreadFunction + * value that will be called at the start of the new thread's life. + * Required. + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: the name of the new thread, which + * might be available to debuggers. Optional, defaults to NULL. + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: an arbitrary app-defined + * pointer, which is passed to the entry function on the new thread, as its + * only parameter. Optional, defaults to NULL. + * - `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`: the size, in bytes, of the new + * thread's stack. Optional, defaults to 0 (system-defined default). + * + * SDL makes an attempt to report `SDL_PROP_THREAD_CREATE_NAME_STRING` to the + * system, so that debuggers can display it. Not all platforms support this. + * + * Thread naming is a little complicated: Most systems have very small limits + * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual + * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to + * see what happens with your system's debugger. The name should be UTF-8 (but + * using the naming limits of C identifiers is a better bet). There are no + * requirements for thread naming conventions, so long as the string is + * null-terminated UTF-8, but these guidelines are helpful in choosing a name: + * + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for it + * (truncate, etc), but the original string contents will be available from + * SDL_GetThreadName(). + * + * The size (in bytes) of the new stack can be specified with + * `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`. Zero means "use the system + * default" which might be wildly different between platforms. x86 Linux + * generally defaults to eight megabytes, an embedded device might be a few + * kilobytes instead. You generally need to specify a stack that is a multiple + * of the system's page size (in many cases, this is 4 kilobytes, but check + * your system documentation). + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * The actual symbol in SDL is `SDL_CreateThreadWithPropertiesRuntime`, so + * there is no symbol clash, but trying to load an SDL shared library and look + * for "SDL_CreateThreadWithProperties" will fail. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param props the properties to use. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ +extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "SDL.thread.create.entry_function" +#define SDL_PROP_THREAD_CREATE_NAME_STRING "SDL.thread.create.name" +#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "SDL.thread.create.userdata" +#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "SDL.thread.create.stacksize" + +/* end wiki documentation for macros that are meant to look like functions. */ +#endif + + +/* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +# if defined(SDL_PLATFORM_WINDOWS) +# ifndef SDL_BeginThreadFunction +# define SDL_BeginThreadFunction _beginthreadex +# endif +# ifndef SDL_EndThreadFunction +# define SDL_EndThreadFunction _endthreadex +# endif +# endif +#endif + +/* currently no other platforms than Windows use _beginthreadex/_endthreadex things. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +# ifndef SDL_BeginThreadFunction +# define SDL_BeginThreadFunction NULL +# endif +#endif + +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +# ifndef SDL_EndThreadFunction +# define SDL_EndThreadFunction NULL +# endif +#endif + +#ifndef SDL_WIKI_DOCUMENTATION_SECTION +/* These are the actual functions exported from SDL! Don't use them directly! Use the SDL_CreateThread and SDL_CreateThreadWithProperties macros! */ +/** + * The actual entry point for SDL_CreateThread. + * + * \param fn the SDL_ThreadFunction function to call in the new thread + * \param name the name of the thread + * \param data a pointer that is passed to `fn` + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be NULL. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be NULL. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); + +/** + * The actual entry point for SDL_CreateThreadWithProperties. + * + * \param props the properties to use + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be NULL. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be NULL. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); + +#define SDL_CreateThread(fn, name, data) SDL_CreateThreadRuntime((fn), (name), (data), (SDL_FunctionPointer) (SDL_BeginThreadFunction), (SDL_FunctionPointer) (SDL_EndThreadFunction)) +#define SDL_CreateThreadWithProperties(props) SDL_CreateThreadWithPropertiesRuntime((props), (SDL_FunctionPointer) (SDL_BeginThreadFunction), (SDL_FunctionPointer) (SDL_EndThreadFunction)) +#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "SDL.thread.create.entry_function" +#define SDL_PROP_THREAD_CREATE_NAME_STRING "SDL.thread.create.name" +#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "SDL.thread.create.userdata" +#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "SDL.thread.create.stacksize" +#endif + + +/** + * Get the thread name as it was specified in SDL_CreateThread(). + * + * \param thread the thread to query. + * \returns a pointer to a UTF-8 string that names the specified thread, or + * NULL if it doesn't have a name. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); + +/** + * Get the thread identifier for the current thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * This function also returns a valid thread ID when called from the main + * thread. + * + * \returns the ID of the current thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetThreadID + */ +extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); + +/** + * Get the thread identifier for the specified thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * \param thread the thread to query. + * \returns the ID of the specified thread, or the ID of the current thread if + * `thread` is NULL. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentThreadID + */ +extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); + +/** + * Set the priority for the current thread. + * + * Note that some platforms will not let you alter the priority (or at least, + * promote the thread to a higher priority) at all, and some require you to be + * an administrator account. Be prepared for this to fail. + * + * \param priority the SDL_ThreadPriority to set. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); + +/** + * Wait for a thread to finish. + * + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. As + * such, only one thread may call SDL_WaitThread() on another. + * + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not both, or + * behavior is undefined. + * + * It is safe to pass a NULL thread to this function; it is a no-op. + * + * Note that the thread pointer is freed by this function and is not valid + * afterward. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_DetachThread + */ +extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); + +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + +/** + * Let a thread clean up on exit without intervention. + * + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread is + * useful for long-running threads that nothing needs to synchronize with or + * further manage. When a detached thread is done, it simply goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon the + * detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is + * not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. Use + * either that function or this one, but not both, or behavior is undefined. + * + * It is safe to pass NULL to this function; it is a no-op. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ +extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); + +/** + * Get the current thread's value associated with a thread local storage ID. + * + * \param id a pointer to the thread local storage ID, may not be NULL. + * \returns the value associated with the ID for the current thread or NULL if + * no value has been set; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTLS + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); + +/** + * The callback used to cleanup data passed to SDL_SetTLS. + * + * This is called when a thread exits, to allow an app to free any resources. + * + * \param value a pointer previously handed to SDL_SetTLS. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTLS + */ +typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); + +/** + * Set the current thread's value associated with a thread local storage ID. + * + * If the thread local storage ID is not initialized (the value is 0), a new + * ID will be created in a thread-safe way, so all calls using a pointer to + * the same ID will refer to the same local storage. + * + * Note that replacing a value from a previous call to this function on the + * same thread does _not_ call the previous value's destructor! + * + * `destructor` can be NULL; it is assumed that `value` does not need to be + * cleaned up if so. + * + * \param id a pointer to the thread local storage ID, may not be NULL. + * \param value the value to associate with the ID for the current thread. + * \param destructor a function called when the thread exits, to free the + * value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTLS + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); + +/** + * Cleanup all TLS data for this thread. + * + * If you are creating your threads outside of SDL and then calling SDL + * functions, you should call this function before your thread exits, to + * properly clean up SDL memory. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_thread_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_time.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_time.h new file mode 100644 index 0000000000..b6d3f6d0d8 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_time.h @@ -0,0 +1,231 @@ +/* +Simple DirectMedia Layer +Copyright (C) 1997-2025 Sam Lantinga + +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. +3. This notice may not be removed or altered from any source distribution. +*/ + +#ifndef SDL_time_h_ +#define SDL_time_h_ + +/** + * # CategoryTime + * + * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. + */ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * A structure holding a calendar date and time broken down into its + * components. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_DateTime +{ + int year; /**< Year */ + int month; /**< Month [01-12] */ + int day; /**< Day of the month [01-31] */ + int hour; /**< Hour [0-23] */ + int minute; /**< Minute [0-59] */ + int second; /**< Seconds [0-60] */ + int nanosecond; /**< Nanoseconds [0-999999999] */ + int day_of_week; /**< Day of the week [0-6] (0 being Sunday) */ + int utc_offset; /**< Seconds east of UTC */ +} SDL_DateTime; + +/** + * The preferred date format of the current system locale. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetDateTimeLocalePreferences + */ +typedef enum SDL_DateFormat +{ + SDL_DATE_FORMAT_YYYYMMDD = 0, /**< Year/Month/Day */ + SDL_DATE_FORMAT_DDMMYYYY = 1, /**< Day/Month/Year */ + SDL_DATE_FORMAT_MMDDYYYY = 2 /**< Month/Day/Year */ +} SDL_DateFormat; + +/** + * The preferred time format of the current system locale. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetDateTimeLocalePreferences + */ +typedef enum SDL_TimeFormat +{ + SDL_TIME_FORMAT_24HR = 0, /**< 24 hour time */ + SDL_TIME_FORMAT_12HR = 1 /**< 12 hour time */ +} SDL_TimeFormat; + +/** + * Gets the current preferred date and time format for the system locale. + * + * This might be a "slow" call that has to query the operating system. It's + * best to ask for this once and save the results. However, the preferred + * formats can change, usually because the user has changed a system + * preference outside of your program. + * + * \param dateFormat a pointer to the SDL_DateFormat to hold the returned date + * format, may be NULL. + * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time + * format, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); + +/** + * Gets the current value of the system realtime clock in nanoseconds since + * Jan 1, 1970 in Universal Coordinated Time (UTC). + * + * \param ticks the SDL_Time to hold the returned tick count. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); + +/** + * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in + * the SDL_DateTime format. + * + * \param ticks the SDL_Time to be converted. + * \param dt the resulting SDL_DateTime. + * \param localTime the resulting SDL_DateTime will be expressed in local time + * if true, otherwise it will be in Universal Coordinated + * Time (UTC). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); + +/** + * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. + * + * This function ignores the day_of_week member of the SDL_DateTime struct, so + * it may remain unset. + * + * \param dt the source SDL_DateTime. + * \param ticks the resulting SDL_Time. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); + +/** + * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals + * since January 1, 1601). + * + * This function fills in the two 32-bit values of the FILETIME structure. + * + * \param ticks the time to convert. + * \param dwLowDateTime a pointer filled in with the low portion of the + * Windows FILETIME value. + * \param dwHighDateTime a pointer filled in with the high portion of the + * Windows FILETIME value. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); + +/** + * Converts a Windows FILETIME (100-nanosecond intervals since January 1, + * 1601) to an SDL time. + * + * This function takes the two 32-bit values of the FILETIME structure as + * parameters. + * + * \param dwLowDateTime the low portion of the Windows FILETIME value. + * \param dwHighDateTime the high portion of the Windows FILETIME value. + * \returns the converted SDL time. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); + +/** + * Get the number of days in a month for a given year. + * + * \param year the year. + * \param month the month [1-12]. + * \returns the number of days in the requested month or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); + +/** + * Get the day of year for a calendar date. + * + * \param year the year component of the date. + * \param month the month component of the date. + * \param day the day component of the date. + * \returns the day of year [0-365] if the date is valid or -1 on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); + +/** + * Get the day of week for a calendar date. + * + * \param year the year component of the date. + * \param month the month component of the date. + * \param day the day component of the date. + * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or + * -1 on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_time_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_timer.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_timer.h new file mode 100644 index 0000000000..cf94881d57 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_timer.h @@ -0,0 +1,450 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#ifndef SDL_timer_h_ +#define SDL_timer_h_ + +/** + * # CategoryTimer + * + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. + */ + +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) + +/** + * Get the number of milliseconds since SDL library initialization. + * + * \returns an unsigned 64-bit value representing the number of milliseconds + * since the SDL library initialized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); + +/** + * Get the number of nanoseconds since SDL library initialization. + * + * \returns an unsigned 64-bit value representing the number of nanoseconds + * since the SDL library initialized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); + +/** + * Get the current value of the high resolution counter. + * + * This function is typically used for profiling. + * + * The counter values are only meaningful relative to each other. Differences + * between values can be converted to times by using + * SDL_GetPerformanceFrequency(). + * + * \returns the current counter value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPerformanceFrequency + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); + +/** + * Get the count per second of the high resolution counter. + * + * \returns a platform-specific count per second. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPerformanceCounter + */ +extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); + +/** + * Wait a specified number of milliseconds before returning. + * + * This function waits a specified number of milliseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ms the number of milliseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); + +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * will attempt to wait as close to the requested time as possible, busy + * waiting if necessary, but could return later due to OS scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); + +/** + * Definition of the timer ID type. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_TimerID; + +/** + * Function prototype for the millisecond timer callback function. + * + * The callback function is passed the current timer interval and returns the + * next timer interval, in milliseconds. If the returned value is the same as + * the one passed in, the periodic alarm continues, otherwise a new alarm is + * scheduled. If the callback returns 0, the periodic alarm is canceled and + * will be removed. + * + * \param userdata an arbitrary pointer provided by the app through + * SDL_AddTimer, for its own use. + * \param timerID the current timer being processed. + * \param interval the current callback time interval. + * \returns the new callback time interval, or 0 to disable further runs of + * the callback. + * + * \threadsafety SDL may call this callback at any time from a background + * thread; the application is responsible for locking resources + * the callback touches that need to be protected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_AddTimer + */ +typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, Uint32 interval); + +/** + * Call a callback function at a future time. + * + * The callback function is passed the current timer interval and the user + * supplied parameter from the SDL_AddTimer() call and should return the next + * timer interval. If the value returned from the callback is 0, the timer is + * canceled and will be removed. + * + * The callback is run on a separate thread, and for short timeouts can + * potentially be called before this function returns. + * + * Timers take into account the amount of time it took to execute the + * callback. For example, if the callback took 250 ms to execute and returned + * 1000 (ms), the timer would only wait another 750 ms before its next + * iteration. + * + * Timing may be inexact due to OS scheduling. Be sure to note the current + * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your + * callback needs to adjust for variances. + * + * \param interval the timer delay, in milliseconds, passed to `callback`. + * \param callback the SDL_TimerCallback function to call when the specified + * `interval` elapses. + * \param userdata a pointer that is passed to `callback`. + * \returns a timer ID or 0 on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddTimerNS + * \sa SDL_RemoveTimer + */ +extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerCallback callback, void *userdata); + +/** + * Function prototype for the nanosecond timer callback function. + * + * The callback function is passed the current timer interval and returns the + * next timer interval, in nanoseconds. If the returned value is the same as + * the one passed in, the periodic alarm continues, otherwise a new alarm is + * scheduled. If the callback returns 0, the periodic alarm is canceled and + * will be removed. + * + * \param userdata an arbitrary pointer provided by the app through + * SDL_AddTimer, for its own use. + * \param timerID the current timer being processed. + * \param interval the current callback time interval. + * \returns the new callback time interval, or 0 to disable further runs of + * the callback. + * + * \threadsafety SDL may call this callback at any time from a background + * thread; the application is responsible for locking resources + * the callback touches that need to be protected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_AddTimerNS + */ +typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerID, Uint64 interval); + +/** + * Call a callback function at a future time. + * + * The callback function is passed the current timer interval and the user + * supplied parameter from the SDL_AddTimerNS() call and should return the + * next timer interval. If the value returned from the callback is 0, the + * timer is canceled and will be removed. + * + * The callback is run on a separate thread, and for short timeouts can + * potentially be called before this function returns. + * + * Timers take into account the amount of time it took to execute the + * callback. For example, if the callback took 250 ns to execute and returned + * 1000 (ns), the timer would only wait another 750 ns before its next + * iteration. + * + * Timing may be inexact due to OS scheduling. Be sure to note the current + * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your + * callback needs to adjust for variances. + * + * \param interval the timer delay, in nanoseconds, passed to `callback`. + * \param callback the SDL_TimerCallback function to call when the specified + * `interval` elapses. + * \param userdata a pointer that is passed to `callback`. + * \returns a timer ID or 0 on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddTimer + * \sa SDL_RemoveTimer + */ +extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTimerCallback callback, void *userdata); + +/** + * Remove a timer created with SDL_AddTimer(). + * + * \param id the ID of the timer to remove. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddTimer + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_timer_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_touch.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_touch.h new file mode 100644 index 0000000000..64845a1568 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_touch.h @@ -0,0 +1,184 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryTouch + * + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. + */ + +#ifndef SDL_touch_h_ +#define SDL_touch_h_ + +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint64 SDL_FingerID; + +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_TouchDeviceType +{ + SDL_TOUCH_DEVICE_INVALID = -1, + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ +} SDL_TouchDeviceType; + +/** + * Data about a single finger in a multitouch event. + * + * Each touch event is a collection of fingers that are simultaneously in + * contact with the touch device (so a "touch" can be a "multitouch," in + * reality), and this struct reports details of the specific fingers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetTouchFingers + */ +typedef struct SDL_Finger +{ + SDL_FingerID id; /**< the finger ID */ + float x; /**< the x-axis location of the touch event, normalized (0...1) */ + float y; /**< the y-axis location of the touch event, normalized (0...1) */ + float pressure; /**< the quantity of pressure applied, normalized (0...1) */ +} SDL_Finger; + +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) + +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) + + +/** + * Get a list of registered touch devices. + * + * On some platforms SDL first sees the touch device if it was actually used. + * Therefore the returned list might be empty, although devices are available. + * After using all devices at least once the number will be correct. + * + * \param count a pointer filled in with the number of devices returned, may + * be NULL. + * \returns a 0 terminated array of touch device IDs or NULL on failure; call + * SDL_GetError() for more information. This should be freed with + * SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); + +/** + * Get the touch device name as reported from the driver. + * + * \param touchID the touch device instance ID. + * \returns touch device name, or NULL on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); + +/** + * Get the type of the given touch device. + * + * \param touchID the ID of a touch device. + * \returns touch device type. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); + +/** + * Get a list of active fingers for a given touch device. + * + * \param touchID the ID of a touch device. + * \param count a pointer filled in with the number of fingers returned, can + * be NULL. + * \returns a NULL terminated array of SDL_Finger pointers or NULL on failure; + * call SDL_GetError() for more information. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_touch_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_tray.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_tray.h new file mode 100644 index 0000000000..1780b0ba52 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray * SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param count An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry ** SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *count); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry * SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry * SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray * SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_version.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_version.h new file mode 100644 index 0000000000..39579ab8c1 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_version.h @@ -0,0 +1,183 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryVersion + * + * Functionality to query the current SDL version, both as headers the app was + * compiled against, and a library the app is linked to. + */ + +#ifndef SDL_version_h_ +#define SDL_version_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The current major version of SDL headers. + * + * If this were SDL version 3.2.1, this value would be 3. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAJOR_VERSION 3 + +/** + * The current minor version of the SDL headers. + * + * If this were SDL version 3.2.1, this value would be 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MINOR_VERSION 2 + +/** + * The current micro (or patchlevel) version of the SDL headers. + * + * If this were SDL version 3.2.1, this value would be 1. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MICRO_VERSION 18 + +/** + * This macro turns the version numbers into a numeric value. + * + * (1,2,3) becomes 1002003. + * + * \param major the major version number. + * \param minor the minorversion number. + * \param patch the patch version number. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_VERSIONNUM(major, minor, patch) \ + ((major) * 1000000 + (minor) * 1000 + (patch)) + +/** + * This macro extracts the major version from a version number + * + * 1002003 becomes 1. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) + +/** + * This macro extracts the minor version from a version number + * + * 1002003 becomes 2. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) + +/** + * This macro extracts the micro version from a version number + * + * 1002003 becomes 3. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) + +/** + * This is the version number macro for the current SDL version. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion + */ +#define SDL_VERSION \ + SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) + +/** + * This macro will evaluate to true if compiled with SDL at least X.Y.Z. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_VERSION_ATLEAST(X, Y, Z) \ + (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) + +/** + * Get the version of SDL that is linked against your program. + * + * If you are linking to SDL dynamically, then it is possible that the current + * version will be different than the version you compiled against. This + * function returns the current version, while SDL_VERSION is the version you + * compiled with. + * + * This function may be called safely at any time, even before SDL_Init(). + * + * \returns the version of the linked library. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRevision + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); + +/** + * Get the code revision of SDL that is linked against your program. + * + * This value is the revision of the code you are linked with and may be + * different from the code you are compiling with, which is found in the + * constant SDL_REVISION. + * + * The revision is arbitrary string (a hash value) uniquely identifying the + * exact revision of the SDL library in use, and is only useful in comparing + * against other revisions. It is NOT an incrementing number. + * + * If SDL wasn't built from a git repository with the appropriate tools, this + * will return an empty string. + * + * You shouldn't use this function for anything but logging it for debugging + * purposes. The string is not intended to be reliable in any way. + * + * \returns an arbitrary string, uniquely identifying the exact revision of + * the SDL library in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetVersion + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetRevision(void); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_version_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_video.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_video.h new file mode 100644 index 0000000000..3b3676d14e --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_video.h @@ -0,0 +1,3311 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryVideo + * + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). + */ + +#ifndef SDL_video_h_ +#define SDL_video_h_ + +#include +#include +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * This is a unique ID for a display for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the display is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_DisplayID; + +/** + * This is a unique ID for a window. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_WindowID; + +/* Global video properties... */ + +/** + * The pointer to the global `wl_display` object used by the Wayland video + * backend. + * + * Can be set before the video subsystem is initialized to import an external + * `wl_display` object from an application or toolkit for use in SDL, or read + * after initialization to export the `wl_display` used by the Wayland video + * backend. Setting this property after the video subsystem has been + * initialized has no effect, and reading it when the video subsystem is + * uninitialized will either return the user provided value, if one was set + * prior to initialization, or NULL. See docs/README-wayland.md for more + * information. + */ +#define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display" + +/** + * System theme. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_SystemTheme +{ + SDL_SYSTEM_THEME_UNKNOWN, /**< Unknown system theme */ + SDL_SYSTEM_THEME_LIGHT, /**< Light colored system theme */ + SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ +} SDL_SystemTheme; + +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ +typedef struct SDL_DisplayModeData SDL_DisplayModeData; + +/** + * The structure that defines a display mode. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetFullscreenDisplayModes + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_SetWindowFullscreenMode + * \sa SDL_GetWindowFullscreenMode + */ +typedef struct SDL_DisplayMode +{ + SDL_DisplayID displayID; /**< the display this mode is associated with */ + SDL_PixelFormat format; /**< pixel format */ + int w; /**< width */ + int h; /**< height */ + float pixel_density; /**< scale converting size to pixels (e.g. a 1920x1080 mode with 2.0 scale would have 3840x2160 pixels) */ + float refresh_rate; /**< refresh rate (or 0.0f for unspecified) */ + int refresh_rate_numerator; /**< precise refresh rate numerator (or 0 for unspecified) */ + int refresh_rate_denominator; /**< precise refresh rate denominator */ + + SDL_DisplayModeData *internal; /**< Private */ + +} SDL_DisplayMode; + +/** + * Display orientation values; the way a display is rotated. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_DisplayOrientation +{ + SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ + SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ + SDL_ORIENTATION_LANDSCAPE_FLIPPED, /**< The display is in landscape mode, with the left side up, relative to portrait mode */ + SDL_ORIENTATION_PORTRAIT, /**< The display is in portrait mode */ + SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */ +} SDL_DisplayOrientation; + +/** + * The struct used as an opaque handle to a window. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateWindow + */ +typedef struct SDL_Window SDL_Window; + +/** + * The flags on a window. + * + * These cover a lot of true/false, or on/off, window state. Some of it is + * immutable after being set through SDL_CreateWindow(), some of it can be + * changed on existing windows by the app, and some of it might be altered by + * the user or system outside of the app's control. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFlags + */ +typedef Uint64 SDL_WindowFlags; + +#define SDL_WINDOW_FULLSCREEN SDL_UINT64_C(0x0000000000000001) /**< window is in fullscreen mode */ +#define SDL_WINDOW_OPENGL SDL_UINT64_C(0x0000000000000002) /**< window usable with OpenGL context */ +#define SDL_WINDOW_OCCLUDED SDL_UINT64_C(0x0000000000000004) /**< window is occluded */ +#define SDL_WINDOW_HIDDEN SDL_UINT64_C(0x0000000000000008) /**< window is neither mapped onto the desktop nor shown in the taskbar/dock/window list; SDL_ShowWindow() is required for it to become visible */ +#define SDL_WINDOW_BORDERLESS SDL_UINT64_C(0x0000000000000010) /**< no window decoration */ +#define SDL_WINDOW_RESIZABLE SDL_UINT64_C(0x0000000000000020) /**< window can be resized */ +#define SDL_WINDOW_MINIMIZED SDL_UINT64_C(0x0000000000000040) /**< window is minimized */ +#define SDL_WINDOW_MAXIMIZED SDL_UINT64_C(0x0000000000000080) /**< window is maximized */ +#define SDL_WINDOW_MOUSE_GRABBED SDL_UINT64_C(0x0000000000000100) /**< window has grabbed mouse input */ +#define SDL_WINDOW_INPUT_FOCUS SDL_UINT64_C(0x0000000000000200) /**< window has input focus */ +#define SDL_WINDOW_MOUSE_FOCUS SDL_UINT64_C(0x0000000000000400) /**< window has mouse focus */ +#define SDL_WINDOW_EXTERNAL SDL_UINT64_C(0x0000000000000800) /**< window not created by SDL */ +#define SDL_WINDOW_MODAL SDL_UINT64_C(0x0000000000001000) /**< window is modal */ +#define SDL_WINDOW_HIGH_PIXEL_DENSITY SDL_UINT64_C(0x0000000000002000) /**< window uses high pixel density back buffer if possible */ +#define SDL_WINDOW_MOUSE_CAPTURE SDL_UINT64_C(0x0000000000004000) /**< window has mouse captured (unrelated to MOUSE_GRABBED) */ +#define SDL_WINDOW_MOUSE_RELATIVE_MODE SDL_UINT64_C(0x0000000000008000) /**< window has relative mode enabled */ +#define SDL_WINDOW_ALWAYS_ON_TOP SDL_UINT64_C(0x0000000000010000) /**< window should always be above others */ +#define SDL_WINDOW_UTILITY SDL_UINT64_C(0x0000000000020000) /**< window should be treated as a utility window, not showing in the task bar and window list */ +#define SDL_WINDOW_TOOLTIP SDL_UINT64_C(0x0000000000040000) /**< window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window */ +#define SDL_WINDOW_POPUP_MENU SDL_UINT64_C(0x0000000000080000) /**< window should be treated as a popup menu, requires a parent window */ +#define SDL_WINDOW_KEYBOARD_GRABBED SDL_UINT64_C(0x0000000000100000) /**< window has grabbed keyboard input */ +#define SDL_WINDOW_VULKAN SDL_UINT64_C(0x0000000010000000) /**< window usable for Vulkan surface */ +#define SDL_WINDOW_METAL SDL_UINT64_C(0x0000000020000000) /**< window usable for Metal view */ +#define SDL_WINDOW_TRANSPARENT SDL_UINT64_C(0x0000000040000000) /**< window with transparent buffer */ +#define SDL_WINDOW_NOT_FOCUSABLE SDL_UINT64_C(0x0000000080000000) /**< window should not be focusable */ + + +/** + * 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.2.0. + */ +#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * 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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#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.2.0. + */ +#define SDL_WINDOWPOS_ISCENTERED(X) \ + (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + + +/** + * Window flash operation. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_FlashOperation +{ + SDL_FLASH_CANCEL, /**< Cancel any window flash state */ + SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */ + SDL_FLASH_UNTIL_FOCUSED /**< Flash the window until it gets focus */ +} SDL_FlashOperation; + +/** + * An opaque handle to an OpenGL context. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GL_CreateContext + */ +typedef struct SDL_GLContextState *SDL_GLContext; + +/** + * Opaque type for an EGL display. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef int SDL_EGLint; + +/** + * EGL platform attribute initialization callback. + * + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); + +/** + * An enumeration of OpenGL configuration attributes. + * + * While you can set most OpenGL attributes normally, the attributes listed + * above must be known before SDL creates the window that will be used with + * the OpenGL context. These attributes are set and read with + * SDL_GL_SetAttribute() and SDL_GL_GetAttribute(). + * + * In some cases, these attributes are minimum requests; the GL does not + * promise to give you exactly what you asked for. It's possible to ask for a + * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask + * for no stencil buffer and still have one available. Context creation should + * fail if the GL can't provide your requested attributes at a minimum, but + * you should check to see exactly what you got. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_GLAttr +{ + SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 8. */ + SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 8. */ + SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 8. */ + SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 8. */ + SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */ + SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */ + SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */ + SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ + SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ + SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */ + SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ + SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ + SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ + SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ + SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ + SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ + SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ + SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ + SDL_GL_CONTEXT_NO_ERROR, + SDL_GL_FLOATBUFFERS, + SDL_GL_EGL_PLATFORM +} SDL_GLAttr; + +/** + * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + + +/** + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + + +/** + * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR + * attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + + +/** + * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + + +/* Function prototypes */ + +/** + * Get the number of video drivers compiled into SDL. + * + * \returns the number of built in video drivers. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetVideoDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); + +/** + * Get the name of a built in video driver. + * + * The video drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "cocoa", + * "x11" or "windows". These never have Unicode characters, and are not meant + * to be proper names. + * + * \param index the index of a video driver. + * \returns the name of the video driver with the given **index**. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumVideoDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); + +/** + * Get the name of the currently initialized video driver. + * + * The names of drivers are all simple, low-ASCII identifiers, like "cocoa", + * "x11" or "windows". These never have Unicode characters, and are not meant + * to be proper names. + * + * \returns the name of the current video driver or NULL if no driver has been + * initialized. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumVideoDrivers + * \sa SDL_GetVideoDriver + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); + +/** + * Get the current system theme. + * + * \returns the current system theme, light, dark, or unknown. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); + +/** + * Get a list of currently connected displays. + * + * \param count a pointer filled in with the number of displays returned, may + * be NULL. + * \returns a 0 terminated array of display instance IDs or NULL on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); + +/** + * Return the primary display. + * + * \returns the instance ID of the primary display on success or 0 on failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); + +/** + * Get the properties associated with a display. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN`: true if the display has HDR + * headroom above the SDR white point. This is for informational and + * diagnostic purposes only, as not all platforms provide this information + * at the display level. + * + * On KMS/DRM: + * + * - `SDL_PROP_DISPLAY_KMSDRM_PANEL_ORIENTATION_NUMBER`: the "panel + * orientation" property for the display in degrees of clockwise rotation. + * Note that this is provided only as a hint, and the application is + * responsible for any coordinate transformations needed to conform to the + * requested display orientation. + * + * \param displayID the instance ID of the display to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); + +#define SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN "SDL.display.HDR_enabled" +#define SDL_PROP_DISPLAY_KMSDRM_PANEL_ORIENTATION_NUMBER "SDL.display.KMSDRM.panel_orientation" + +/** + * Get the name of a display in UTF-8 encoding. + * + * \param displayID the instance ID of the display to query. + * \returns the name of a display or NULL on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displayID); + +/** + * Get the desktop area represented by a display. + * + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. + * + * \param displayID the instance ID of the display to query. + * \param rect the SDL_Rect structure filled in with the display bounds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplayUsableBounds + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); + +/** + * Get the usable desktop area represented by a display, in screen + * coordinates. + * + * This is the same area as SDL_GetDisplayBounds() reports, but with portions + * reserved by the system removed. For example, on Apple's macOS, this + * subtracts the area occupied by the menu bar and dock. + * + * Setting a window to be fullscreen generally bypasses these unusable areas, + * so these are good guidelines for the maximum space available to a + * non-fullscreen window. + * + * \param displayID the instance ID of the display to query. + * \param rect the SDL_Rect structure filled in with the display bounds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); + +/** + * Get the orientation of a display when it is unrotated. + * + * \param displayID the instance ID of the display to query. + * \returns the SDL_DisplayOrientation enum value of the display, or + * `SDL_ORIENTATION_UNKNOWN` if it isn't available. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientation(SDL_DisplayID displayID); + +/** + * Get the orientation of a display. + * + * \param displayID the instance ID of the display to query. + * \returns the SDL_DisplayOrientation enum value of the display, or + * `SDL_ORIENTATION_UNKNOWN` if it isn't available. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientation(SDL_DisplayID displayID); + +/** + * Get the content scale of a display. + * + * The content scale is the expected scale for content based on the DPI + * settings of the display. For example, a 4K display might have a 2.0 (200%) + * display scale, which means that the user expects UI elements to be twice as + * big on this display, to aid in readability. + * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * + * \param displayID the instance ID of the display to query. + * \returns the content scale of the display, or 0.0f on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); + +/** + * Get a list of fullscreen display modes available on a display. + * + * The display modes are sorted in this priority: + * + * - w -> largest to smallest + * - h -> largest to smallest + * - bits per pixel -> more colors to fewer colors + * - packed pixel layout -> largest to smallest + * - refresh rate -> highest to lowest + * - pixel density -> lowest to highest + * + * \param displayID the instance ID of the display to query. + * \param count a pointer filled in with the number of display modes returned, + * may be NULL. + * \returns a NULL terminated array of display mode pointers or NULL on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL_DisplayID displayID, int *count); + +/** + * Get the closest match to the requested display mode. + * + * The available display modes are scanned and `closest` is filled in with the + * closest mode matching the requested mode and returned. The mode format and + * refresh rate default to the desktop mode if they are set to 0. The modes + * are scanned with size being first priority, format being second priority, + * and finally checking the refresh rate. If all the available modes are too + * small, then false is returned. + * + * \param displayID the instance ID of the display to query. + * \param w the width in pixels of the desired display mode. + * \param h the height in pixels of the desired display mode. + * \param refresh_rate the refresh rate of the desired display mode, or 0.0f + * for the desktop refresh rate. + * \param include_high_density_modes boolean to include high density modes in + * the search. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplays + * \sa SDL_GetFullscreenDisplayModes + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); + +/** + * Get information about the desktop's display mode. + * + * There's a difference between this function and SDL_GetCurrentDisplayMode() + * when SDL runs fullscreen and has changed the resolution. In that case this + * function will return the previous native display mode, and not the current + * display mode. + * + * \param displayID the instance ID of the display to query. + * \returns a pointer to the desktop display mode or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayID displayID); + +/** + * Get information about the current display mode. + * + * There's a difference between this function and SDL_GetDesktopDisplayMode() + * when SDL runs fullscreen and has changed the resolution. In that case this + * function will return the current display mode, and not the previous native + * display mode. + * + * \param displayID the instance ID of the display to query. + * \returns a pointer to the desktop display mode or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayID displayID); + +/** + * Get the display containing a point. + * + * \param point the point to query. + * \returns the instance ID of the display containing the point or 0 on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point *point); + +/** + * Get the display primarily containing a rect. + * + * \param rect the rect to query. + * \returns the instance ID of the display entirely containing the rect or + * closest to the center of the rect on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect *rect); + +/** + * Get the display associated with a window. + * + * \param window the window to query. + * \returns the instance ID of the display containing the center of the window + * on success or 0 on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDisplayBounds + * \sa SDL_GetDisplays + */ +extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window); + +/** + * Get the pixel density of a window. + * + * This is a ratio of pixel size to window size. For example, if the window is + * 1920x1080 and it has a high density back buffer of 3840x2160 pixels, it + * would have a pixel density of 2.0. + * + * \param window the window to query. + * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); + +/** + * Get the content display scale relative to a window's pixel size. + * + * This is a combination of the window pixel density and the display content + * scale, and is the expected scale for displaying content in this window. For + * example, if a 3840x2160 window had a display scale of 2.0, the user expects + * the content to take twice as many pixels and be the same physical size as + * if it were being displayed in a 1920x1080 window with a display scale of + * 1.0. + * + * Conceptually this value corresponds to the scale display setting, and is + * updated when that setting is changed, or the window moves to a display with + * a different scale setting. + * + * \param window the window to query. + * \returns the display scale, or 0.0f on failure; call SDL_GetError() for + * more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); + +/** + * Set the display mode to use when a window is visible and fullscreen. + * + * This only affects the display mode used when the window is fullscreen. To + * change the window size when the window is not fullscreen, use + * SDL_SetWindowSize(). + * + * If the window is currently in the fullscreen state, this request is + * asynchronous on some windowing systems and the new mode dimensions may not + * be applied immediately upon the return of this function. If an immediate + * change is required, call SDL_SyncWindow() to block until the changes have + * taken effect. + * + * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. + * + * \param window the window to affect. + * \param mode a pointer to the display mode to use, which can be NULL for + * borderless fullscreen desktop mode, or one of the fullscreen + * modes returned by SDL_GetFullscreenDisplayModes() to set an + * exclusive fullscreen mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFullscreenMode + * \sa SDL_SetWindowFullscreen + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); + +/** + * Query the display mode to use when a window is visible at fullscreen. + * + * \param window the window to query. + * \returns a pointer to the exclusive fullscreen mode to use or NULL for + * borderless fullscreen desktop mode. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowFullscreenMode + * \sa SDL_SetWindowFullscreen + */ +extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(SDL_Window *window); + +/** + * Get the raw ICC profile data for the screen the window is currently on. + * + * \param window the window to query. + * \param size the size of the ICC profile. + * \returns the raw ICC profile data on success or NULL on failure; call + * SDL_GetError() for more information. This should be freed with + * SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); + +/** + * Get the pixel format associated with the window. + * + * \param window the window to query. + * \returns the pixel format of the window on success or + * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); + +/** + * Get a list of valid windows. + * + * \param count a pointer filled in with the number of windows returned, may + * be NULL. + * \returns a NULL terminated array of SDL_Window pointers or NULL on failure; + * call SDL_GetError() for more information. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); + +/** + * Create a window with the specified dimensions and flags. + * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * + * `flags` may be any of the following OR'd together: + * + * - `SDL_WINDOW_FULLSCREEN`: fullscreen window at desktop resolution + * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context + * - `SDL_WINDOW_OCCLUDED`: window partially or completely obscured by another + * window + * - `SDL_WINDOW_HIDDEN`: window is not visible + * - `SDL_WINDOW_BORDERLESS`: no window decoration + * - `SDL_WINDOW_RESIZABLE`: window can be resized + * - `SDL_WINDOW_MINIMIZED`: window is minimized + * - `SDL_WINDOW_MAXIMIZED`: window is maximized + * - `SDL_WINDOW_MOUSE_GRABBED`: window has grabbed mouse focus + * - `SDL_WINDOW_INPUT_FOCUS`: window has input focus + * - `SDL_WINDOW_MOUSE_FOCUS`: window has mouse focus + * - `SDL_WINDOW_EXTERNAL`: window not created by SDL + * - `SDL_WINDOW_MODAL`: window is modal + * - `SDL_WINDOW_HIGH_PIXEL_DENSITY`: window uses high pixel density back + * buffer if possible + * - `SDL_WINDOW_MOUSE_CAPTURE`: window has mouse captured (unrelated to + * MOUSE_GRABBED) + * - `SDL_WINDOW_ALWAYS_ON_TOP`: window should always be above others + * - `SDL_WINDOW_UTILITY`: window should be treated as a utility window, not + * showing in the task bar and window list + * - `SDL_WINDOW_TOOLTIP`: window should be treated as a tooltip and does not + * get mouse or keyboard focus, requires a parent window + * - `SDL_WINDOW_POPUP_MENU`: window should be treated as a popup menu, + * requires a parent window + * - `SDL_WINDOW_KEYBOARD_GRABBED`: window has grabbed keyboard input + * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance + * - `SDL_WINDOW_METAL`: window usable with a Metal instance + * - `SDL_WINDOW_TRANSPARENT`: window with transparent buffer + * - `SDL_WINDOW_NOT_FOCUSABLE`: window should not be focusable + * + * The SDL_Window is implicitly shown if SDL_WINDOW_HIDDEN is not set. + * + * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist + * property to YES, otherwise you will not receive a High-DPI OpenGL canvas. + * + * The window pixel size may differ from its window coordinate size if the + * window is on a high pixel density display. Use SDL_GetWindowSize() to query + * the client area's size in window coordinates, and + * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the + * drawable size in pixels. Note that the drawable size can vary after the + * window is created and should be queried again if you get an + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. + * + * If the window is created with any of the SDL_WINDOW_OPENGL or + * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function + * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the + * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). + * + * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. + * + * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, + * SDL_CreateWindow() will fail. + * + * If you intend to use this window with an SDL_Renderer, you should use + * SDL_CreateWindowAndRenderer() instead of this function, to avoid window + * flicker. + * + * On non-Apple devices, SDL requires you to either not link to the Vulkan + * loader or link to a dynamic library version. This limitation may be removed + * in a future version of SDL. + * + * \param title the title of the window, in UTF-8 encoding. + * \param w the width of the window. + * \param h the height of the window. + * \param flags 0, or one or more SDL_WindowFlags OR'd together. + * \returns the window that was created or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer + * \sa SDL_CreatePopupWindow + * \sa SDL_CreateWindowWithProperties + * \sa SDL_DestroyWindow + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int w, int h, SDL_WindowFlags flags); + +/** + * Create a child popup window of the specified parent window. + * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. + * + * The following flags are not relevant to popup window creation and will be + * ignored: + * + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` + * + * The parent parameter **must** be non-null and a valid window. The parent of + * a popup window can be either a regular, toplevel window, or another popup + * window. + * + * Popup windows cannot be minimized, maximized, made fullscreen, raised, + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. + * + * Popup windows implicitly do not have a border/decorations and do not appear + * on the taskbar/dock or in lists of windows such as alt-tab menus. + * + * By default, popup window positions will automatically be constrained to keep + * the entire window within display bounds. This can be overridden with the + * `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN` property. + * + * By default, popup menus will automatically grab keyboard focus from the parent + * when shown. This behavior can be overridden by setting the `SDL_WINDOW_NOT_FOCUSABLE` + * flag, setting the `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN` property to false, or + * toggling it after creation via the `SDL_SetWindowFocusable()` function. + * + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. + * + * \param parent the parent of the window, must not be NULL. + * \param offset_x the x position of the popup window relative to the origin + * of the parent. + * \param offset_y the y position of the popup window relative to the origin + * of the parent window. + * \param w the width of the window. + * \param h the height of the window. + * \param flags SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, and zero or more + * additional SDL_WindowFlags OR'd together. + * \returns the window that was created or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindow + * \sa SDL_CreateWindowWithProperties + * \sa SDL_DestroyWindow + * \sa SDL_GetWindowParent + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, SDL_WindowFlags flags); + +/** + * Create a window with the specified properties. + * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * + * These are the supported properties: + * + * - `SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN`: true if the window should + * be always on top + * - `SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN`: true if the window has no + * window decoration + * - `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN`: true if the "tooltip" and + * "menu" window types should be automatically constrained to be entirely within + * display bounds (default), false if no constraints on the position are desired. + * - `SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN`: true if the + * window will be used with an externally managed graphics context. + * - `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN`: true if the window should + * accept keyboard input (defaults true) + * - `SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN`: true if the window should + * start in fullscreen mode at desktop resolution + * - `SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER`: the height of the window + * - `SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN`: true if the window should start + * hidden + * - `SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN`: true if the window + * uses a high pixel density buffer if possible + * - `SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN`: true if the window should + * start maximized + * - `SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN`: true if the window is a popup menu + * - `SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN`: true if the window will be used + * with Metal rendering + * - `SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN`: true if the window should + * start minimized + * - `SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN`: true if the window is modal to + * its parent + * - `SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN`: true if the window starts + * with grabbed mouse focus + * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used + * with OpenGL rendering + * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the + * parent of this window, required for windows with the "tooltip", "menu", + * and "modal" properties + * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be + * resizable + * - `SDL_PROP_WINDOW_CREATE_TITLE_STRING`: the title of the window, in UTF-8 + * encoding + * - `SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN`: true if the window show + * transparent in the areas with alpha of 0 + * - `SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN`: true if the window is a tooltip + * - `SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN`: true if the window is a utility + * window, not showing in the task bar and window list + * - `SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN`: true if the window will be used + * with Vulkan rendering + * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window + * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or + * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is + * relative to the parent for windows with the "tooltip" or "menu" property + * set. + * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or + * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is + * relative to the parent for windows with the "tooltip" or "menu" property + * set. + * + * These are additional supported properties on macOS: + * + * - `SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER`: the + * `(__unsafe_unretained)` NSWindow associated with the window, if you want + * to wrap an existing window. + * - `SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER`: the `(__unsafe_unretained)` + * NSView associated with the window, defaults to `[window contentView]` + * + * These are additional supported properties on Wayland: + * + * - `SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN` - true if + * the application wants to use the Wayland surface for a custom role and + * does not want it attached to an XDG toplevel window. See + * [README/wayland](README/wayland) for more information on using custom + * surfaces. + * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. + * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface + * associated with the window, if you want to wrap an existing window. See + * [README/wayland](README/wayland) for more information. + * + * These are additional supported properties on Windows: + * + * - `SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER`: the HWND associated with the + * window, if you want to wrap an existing window. + * - `SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER`: optional, + * another window to share pixel format with, useful for OpenGL windows + * + * These are additional supported properties with X11: + * + * - `SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER`: the X11 Window associated + * with the window, if you want to wrap an existing window. + * + * The window is implicitly shown if the "hidden" property is not set. + * + * Windows with the "tooltip" and "menu" properties are popup windows and have + * the behaviors and guidelines outlined in SDL_CreatePopupWindow(). + * + * If this window is being created to be used with an SDL_Renderer, you should + * not add a graphics API specific property + * (`SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`, etc), as SDL will handle that + * internally when it chooses a renderer. However, SDL might need to recreate + * your window at that point, which may cause the window to appear briefly, + * and then flicker as it is recreated. The correct approach to this is to + * create the window with the `SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN` property + * set to true, then create the renderer, then show the window with + * SDL_ShowWindow(). + * + * \param props the properties to use. + * \returns the window that was created or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProperties + * \sa SDL_CreateWindow + * \sa SDL_DestroyWindow + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "SDL.window.create.always_on_top" +#define SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN "SDL.window.create.borderless" +#define SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN "SDL.window.create.constrain_popup" +#define SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN "SDL.window.create.focusable" +#define SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN "SDL.window.create.external_graphics_context" +#define SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER "SDL.window.create.flags" +#define SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN "SDL.window.create.fullscreen" +#define SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER "SDL.window.create.height" +#define SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN "SDL.window.create.hidden" +#define SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN "SDL.window.create.high_pixel_density" +#define SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN "SDL.window.create.maximized" +#define SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN "SDL.window.create.menu" +#define SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN "SDL.window.create.metal" +#define SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN "SDL.window.create.minimized" +#define SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN "SDL.window.create.modal" +#define SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN "SDL.window.create.mouse_grabbed" +#define SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN "SDL.window.create.opengl" +#define SDL_PROP_WINDOW_CREATE_PARENT_POINTER "SDL.window.create.parent" +#define SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN "SDL.window.create.resizable" +#define SDL_PROP_WINDOW_CREATE_TITLE_STRING "SDL.window.create.title" +#define SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN "SDL.window.create.transparent" +#define SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN "SDL.window.create.tooltip" +#define SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN "SDL.window.create.utility" +#define SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN "SDL.window.create.vulkan" +#define SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER "SDL.window.create.width" +#define SDL_PROP_WINDOW_CREATE_X_NUMBER "SDL.window.create.x" +#define SDL_PROP_WINDOW_CREATE_Y_NUMBER "SDL.window.create.y" +#define SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER "SDL.window.create.cocoa.window" +#define SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER "SDL.window.create.cocoa.view" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "SDL.window.create.wayland.surface_role_custom" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN "SDL.window.create.wayland.create_egl_window" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER "SDL.window.create.wayland.wl_surface" +#define SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER "SDL.window.create.win32.hwnd" +#define SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER "SDL.window.create.win32.pixel_format_hwnd" +#define SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER "SDL.window.create.x11.window" + +/** + * Get the numeric ID of a window. + * + * The numeric ID is what SDL_WindowEvent references, and is necessary to map + * these events to specific SDL_Window objects. + * + * \param window the window to query. + * \returns the ID of the window on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFromID + */ +extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); + +/** + * Get a window from a stored ID. + * + * The numeric ID is what SDL_WindowEvent references, and is necessary to map + * these events to specific SDL_Window objects. + * + * \param id the ID of the window. + * \returns the window associated with `id` or NULL if it doesn't exist; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowID + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); + +/** + * Get parent of a window. + * + * \param window the window to query. + * \returns the parent of the window on success or NULL if the window has no + * parent. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreatePopupWindow + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window); + +/** + * Get the properties associated with a window. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_WINDOW_SHAPE_POINTER`: the surface associated with a shaped + * window + * - `SDL_PROP_WINDOW_HDR_ENABLED_BOOLEAN`: true if the window has HDR + * headroom above the SDR white point. This property can change dynamically + * when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * - `SDL_PROP_WINDOW_SDR_WHITE_LEVEL_FLOAT`: the value of SDR white in the + * SDL_COLORSPACE_SRGB_LINEAR colorspace. On Windows this corresponds to the + * SDR white level in scRGB colorspace, and on Apple platforms this is + * always 1.0 for EDR content. This property can change dynamically when + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * - `SDL_PROP_WINDOW_HDR_HEADROOM_FLOAT`: the additional high dynamic range + * that can be displayed, in terms of the SDR white point. When HDR is not + * enabled, this will be 1.0. This property can change dynamically when + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. + * + * On Android: + * + * - `SDL_PROP_WINDOW_ANDROID_WINDOW_POINTER`: the ANativeWindow associated + * with the window + * - `SDL_PROP_WINDOW_ANDROID_SURFACE_POINTER`: the EGLSurface associated with + * the window + * + * On iOS: + * + * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` + * UIWindow associated with the window + * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag + * associated with metal views on the window + * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's + * framebuffer object. It must be bound when rendering to the screen using + * OpenGL. + * - `SDL_PROP_WINDOW_UIKIT_OPENGL_RENDERBUFFER_NUMBER`: the OpenGL view's + * renderbuffer object. It must be bound when SDL_GL_SwapWindow is called. + * - `SDL_PROP_WINDOW_UIKIT_OPENGL_RESOLVE_FRAMEBUFFER_NUMBER`: the OpenGL + * view's resolve framebuffer, when MSAA is used. + * + * On KMS/DRM: + * + * - `SDL_PROP_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER`: the device index associated + * with the window (e.g. the X in /dev/dri/cardX) + * - `SDL_PROP_WINDOW_KMSDRM_DRM_FD_NUMBER`: the DRM FD associated with the + * window + * - `SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER`: the GBM device associated + * with the window + * + * On macOS: + * + * - `SDL_PROP_WINDOW_COCOA_WINDOW_POINTER`: the `(__unsafe_unretained)` + * NSWindow associated with the window + * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag + * assocated with metal views on the window + * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * + * On Vivante: + * + * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType + * associated with the window + * - `SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER`: the EGLNativeWindowType + * associated with the window + * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with + * the window + * + * On Windows: + * + * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window + * - `SDL_PROP_WINDOW_WIN32_HDC_POINTER`: the HDC associated with the window + * - `SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER`: the HINSTANCE associated with + * the window + * + * On Wayland: + * + * Note: The `xdg_*` window objects do not internally persist across window + * show/hide calls. They will be null if the window is hidden and must be + * queried each time it is shown. + * + * - `SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER`: the wl_display associated with + * the window + * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with + * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window + * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window + * associated with the window + * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated + * with the window + * - `SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER`: the xdg_toplevel role + * associated with the window + * - 'SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_EXPORT_HANDLE_STRING': the export + * handle associated with the window + * - `SDL_PROP_WINDOW_WAYLAND_XDG_POPUP_POINTER`: the xdg_popup role + * associated with the window + * - `SDL_PROP_WINDOW_WAYLAND_XDG_POSITIONER_POINTER`: the xdg_positioner + * associated with the window, in popup mode + * + * On X11: + * + * - `SDL_PROP_WINDOW_X11_DISPLAY_POINTER`: the X11 Display associated with + * the window + * - `SDL_PROP_WINDOW_X11_SCREEN_NUMBER`: the screen number associated with + * the window + * - `SDL_PROP_WINDOW_X11_WINDOW_NUMBER`: the X11 Window associated with the + * window + * + * \param window the window to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); + +#define SDL_PROP_WINDOW_SHAPE_POINTER "SDL.window.shape" +#define SDL_PROP_WINDOW_HDR_ENABLED_BOOLEAN "SDL.window.HDR_enabled" +#define SDL_PROP_WINDOW_SDR_WHITE_LEVEL_FLOAT "SDL.window.SDR_white_level" +#define SDL_PROP_WINDOW_HDR_HEADROOM_FLOAT "SDL.window.HDR_headroom" +#define SDL_PROP_WINDOW_ANDROID_WINDOW_POINTER "SDL.window.android.window" +#define SDL_PROP_WINDOW_ANDROID_SURFACE_POINTER "SDL.window.android.surface" +#define SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER "SDL.window.uikit.window" +#define SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER "SDL.window.uikit.metal_view_tag" +#define SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER "SDL.window.uikit.opengl.framebuffer" +#define SDL_PROP_WINDOW_UIKIT_OPENGL_RENDERBUFFER_NUMBER "SDL.window.uikit.opengl.renderbuffer" +#define SDL_PROP_WINDOW_UIKIT_OPENGL_RESOLVE_FRAMEBUFFER_NUMBER "SDL.window.uikit.opengl.resolve_framebuffer" +#define SDL_PROP_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER "SDL.window.kmsdrm.dev_index" +#define SDL_PROP_WINDOW_KMSDRM_DRM_FD_NUMBER "SDL.window.kmsdrm.drm_fd" +#define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" +#define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" +#define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" +#define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" +#define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" +#define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" +#define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" +#define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" +#define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" +#define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" +#define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" +#define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" +#define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" +#define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" +#define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_EXPORT_HANDLE_STRING "SDL.window.wayland.xdg_toplevel_export_handle" +#define SDL_PROP_WINDOW_WAYLAND_XDG_POPUP_POINTER "SDL.window.wayland.xdg_popup" +#define SDL_PROP_WINDOW_WAYLAND_XDG_POSITIONER_POINTER "SDL.window.wayland.xdg_positioner" +#define SDL_PROP_WINDOW_X11_DISPLAY_POINTER "SDL.window.x11.display" +#define SDL_PROP_WINDOW_X11_SCREEN_NUMBER "SDL.window.x11.screen" +#define SDL_PROP_WINDOW_X11_WINDOW_NUMBER "SDL.window.x11.window" + +/** + * Get the window flags. + * + * \param window the window to query. + * \returns a mask of the SDL_WindowFlags associated with `window`. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindow + * \sa SDL_HideWindow + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow + * \sa SDL_SetWindowFullscreen + * \sa SDL_SetWindowMouseGrab + * \sa SDL_ShowWindow + */ +extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *window); + +/** + * Set the title of a window. + * + * This string is expected to be in UTF-8 encoding. + * + * \param window the window to change. + * \param title the desired window title in UTF-8 format. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowTitle + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); + +/** + * Get the title of a window. + * + * \param window the window to query. + * \returns the title of the window in UTF-8 format or "" if there is no + * title. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowTitle + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); + +/** + * Set the icon for a window. + * + * If this function is passed a surface with alternate representations, the + * surface will be interpreted as the content to be used for 100% display + * scale, and the alternate representations will be used for high DPI + * situations. For example, if the original surface is 32x32, then on a 2x + * macOS display or 200% display scale on Windows, a 64x64 version of the + * image will be used, if available. If a matching version of the image isn't + * available, the closest larger size image will be downscaled to the + * appropriate size and be used instead, if available. Otherwise, the closest + * smaller image will be upscaled and be used instead. + * + * \param window the window to change. + * \param icon an SDL_Surface structure containing the icon for the window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); + +/** + * Request that the window's position be set. + * + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. + * + * This can be used to reposition fullscreen-desktop windows onto a different + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via + * SDL_SetWindowFullscreenMode(). + * + * On some windowing systems this request is asynchronous and the new + * coordinates may not have have been applied immediately upon the return of + * this function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window position changes, an SDL_EVENT_WINDOW_MOVED event will be + * emitted with the window's new coordinates. Note that the new coordinates + * may not match the exact coordinates requested, as some windowing systems + * can restrict the position of the window in certain scenarios (e.g. + * constraining the position so the window is always within desktop bounds). + * Additionally, as this is just a request, it can be denied by the windowing + * system. + * + * \param window the window to reposition. + * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or + * `SDL_WINDOWPOS_UNDEFINED`. + * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or + * `SDL_WINDOWPOS_UNDEFINED`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowPosition + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); + +/** + * Get the position of a window. + * + * This is the current position of the window as last reported by the + * windowing system. + * + * If you do not need the value for one of the positions a NULL may be passed + * in the `x` or `y` parameter. + * + * \param window the window to query. + * \param x a pointer filled in with the x position of the window, may be + * NULL. + * \param y a pointer filled in with the y position of the window, may be + * NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowPosition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); + +/** + * Request that the size of a window's client area be set. + * + * If the window is in a fullscreen or maximized state, this request has no + * effect. + * + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). + * + * On some windowing systems, this request is asynchronous and the new window + * size may not have have been applied immediately upon the return of this + * function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be + * emitted with the new window dimensions. Note that the new dimensions may + * not match the exact size requested, as some windowing systems can restrict + * the window size in certain scenarios (e.g. constraining the size of the + * content area to remain within the usable desktop bounds). Additionally, as + * this is just a request, it can be denied by the windowing system. + * + * \param window the window to change. + * \param w the width of the window, must be > 0. + * \param h the height of the window, must be > 0. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSize + * \sa SDL_SetWindowFullscreenMode + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); + +/** + * Get the size of a window's client area. + * + * The window pixel size may differ from its window coordinate size if the + * window is on a high pixel density display. Use SDL_GetWindowSizeInPixels() + * or SDL_GetRenderOutputSize() to get the real client area size in pixels. + * + * \param window the window to query the width and height from. + * \param w a pointer filled in with the width of the window, may be NULL. + * \param h a pointer filled in with the height of the window, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRenderOutputSize + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_SetWindowSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); + +/** + * Get the safe area for this window. + * + * Some devices have portions of the screen which are partially obscured or + * not interactive, possibly due to on-screen controls, curved edges, camera + * notches, TV overscan, etc. This function provides the area of the window + * which is safe to have interactable content. You should continue rendering + * into the rest of the window, but it should not contain visually important + * or interactible content. + * + * \param window the window to query. + * \param rect a pointer filled in with the client area that is safe for + * interactive content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); + +/** + * Request that the aspect ratio of a window's client area be set. + * + * The aspect ratio is the ratio of width divided by height, e.g. 2560x1600 + * would be 1.6. Larger aspect ratios are wider and smaller aspect ratios are + * narrower. + * + * If, at the time of this request, the window in a fixed-size state, such as + * maximized or fullscreen, the request will be deferred until the window + * exits this state and becomes resizable again. + * + * On some windowing systems, this request is asynchronous and the new window + * aspect ratio may not have have been applied immediately upon the return of + * this function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be + * emitted with the new window dimensions. Note that the new dimensions may + * not match the exact aspect ratio requested, as some windowing systems can + * restrict the window size in certain scenarios (e.g. constraining the size + * of the content area to remain within the usable desktop bounds). + * Additionally, as this is just a request, it can be denied by the windowing + * system. + * + * \param window the window to change. + * \param min_aspect the minimum aspect ratio of the window, or 0.0f for no + * limit. + * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no + * limit. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowAspectRatio + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); + +/** + * Get the size of a window's client area. + * + * \param window the window to query the width and height from. + * \param min_aspect a pointer filled in with the minimum aspect ratio of the + * window, may be NULL. + * \param max_aspect a pointer filled in with the maximum aspect ratio of the + * window, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowAspectRatio + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); + +/** + * Get the size of a window's borders (decorations) around the client area. + * + * Note: If this function fails (returns false), the size values will be + * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the + * window in question was borderless. + * + * Note: This function may fail on systems where the window has not yet been + * decorated by the display server (for example, immediately after calling + * SDL_CreateWindow). It is recommended that you wait at least until the + * window has been presented and composited, so that the window system has a + * chance to decorate the window and provide the border dimensions to SDL. + * + * This function also returns false if getting the information is not + * supported. + * + * \param window the window to query the size values of the border + * (decorations) from. + * \param top pointer to variable for storing the size of the top border; NULL + * is permitted. + * \param left pointer to variable for storing the size of the left border; + * NULL is permitted. + * \param bottom pointer to variable for storing the size of the bottom + * border; NULL is permitted. + * \param right pointer to variable for storing the size of the right border; + * NULL is permitted. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); + +/** + * Get the size of a window's client area, in pixels. + * + * \param window the window from which the drawable size should be queried. + * \param w a pointer to variable for storing the width in pixels, may be + * NULL. + * \param h a pointer to variable for storing the height in pixels, may be + * NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindow + * \sa SDL_GetWindowSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); + +/** + * Set the minimum size of a window's client area. + * + * \param window the window to change. + * \param min_w the minimum width of the window, or 0 for no limit. + * \param min_h the minimum height of the window, or 0 for no limit. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMinimumSize + * \sa SDL_SetWindowMaximumSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); + +/** + * Get the minimum size of a window's client area. + * + * \param window the window to query. + * \param w a pointer filled in with the minimum width of the window, may be + * NULL. + * \param h a pointer filled in with the minimum height of the window, may be + * NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMaximumSize + * \sa SDL_SetWindowMinimumSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); + +/** + * Set the maximum size of a window's client area. + * + * \param window the window to change. + * \param max_w the maximum width of the window, or 0 for no limit. + * \param max_h the maximum height of the window, or 0 for no limit. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMaximumSize + * \sa SDL_SetWindowMinimumSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); + +/** + * Get the maximum size of a window's client area. + * + * \param window the window to query. + * \param w a pointer filled in with the maximum width of the window, may be + * NULL. + * \param h a pointer filled in with the maximum height of the window, may be + * NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMinimumSize + * \sa SDL_SetWindowMaximumSize + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); + +/** + * Set the border state of a window. + * + * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add + * or remove the border from the actual window. This is a no-op if the + * window's border already matches the requested state. + * + * You can't change the border state of a fullscreen window. + * + * \param window the window of which to change the border state. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFlags + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); + +/** + * Set the user-resizable state of a window. + * + * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and + * allow/disallow user resizing of the window. This is a no-op if the window's + * resizable state already matches the requested state. + * + * You can't change the resizable state of a fullscreen window. + * + * \param window the window of which to change the resizable state. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFlags + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); + +/** + * Set the window to always be above the others. + * + * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This + * will bring the window to the front and keep the window above the rest. + * + * \param window the window of which to change the always on top state. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFlags + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); + +/** + * Show a window. + * + * \param window the window to show. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HideWindow + * \sa SDL_RaiseWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); + +/** + * Hide a window. + * + * \param window the window to hide. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN + */ +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); + +/** + * Request that a window be raised above other windows and gain the input + * focus. + * + * The result of this request is subject to desktop window manager policy, + * particularly if raising the requested window would result in stealing focus + * from another application. If the window is successfully raised and gains + * input focus, an SDL_EVENT_WINDOW_FOCUS_GAINED event will be emitted, and + * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. + * + * \param window the window to raise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); + +/** + * Request that the window be made as large as possible. + * + * Non-resizable windows can't be maximized. The window must have the + * SDL_WINDOW_RESIZABLE flag set, or this will have no effect. + * + * On some windowing systems this request is asynchronous and the new window + * state may not have have been applied immediately upon the return of this + * function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window state changes, an SDL_EVENT_WINDOW_MAXIMIZED event will be + * emitted. Note that, as this is just a request, the windowing system can + * deny the state change. + * + * When maximizing a window, whether the constraints set via + * SDL_SetWindowMaximumSize() are honored depends on the policy of the window + * manager. Win32 and macOS enforce the constraints when maximizing, while X11 + * and Wayland window managers may vary. + * + * \param window the window to maximize. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MinimizeWindow + * \sa SDL_RestoreWindow + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); + +/** + * Request that the window be minimized to an iconic representation. + * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * + * On some windowing systems this request is asynchronous and the new window + * state may not have been applied immediately upon the return of this + * function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window state changes, an SDL_EVENT_WINDOW_MINIMIZED event will be + * emitted. Note that, as this is just a request, the windowing system can + * deny the state change. + * + * \param window the window to minimize. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MaximizeWindow + * \sa SDL_RestoreWindow + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); + +/** + * Request that the size and position of a minimized or maximized window be + * restored. + * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * + * On some windowing systems this request is asynchronous and the new window + * state may not have have been applied immediately upon the return of this + * function. If an immediate change is required, call SDL_SyncWindow() to + * block until the changes have taken effect. + * + * When the window state changes, an SDL_EVENT_WINDOW_RESTORED event will be + * emitted. Note that, as this is just a request, the windowing system can + * deny the state change. + * + * \param window the window to restore. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MaximizeWindow + * \sa SDL_MinimizeWindow + * \sa SDL_SyncWindow + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); + +/** + * Request that the window's fullscreen state be changed. + * + * By default a window in fullscreen state uses borderless fullscreen desktop + * mode, but a specific exclusive display mode can be set using + * SDL_SetWindowFullscreenMode(). + * + * On some windowing systems this request is asynchronous and the new + * fullscreen state may not have have been applied immediately upon the return + * of this function. If an immediate change is required, call SDL_SyncWindow() + * to block until the changes have taken effect. + * + * When the window state changes, an SDL_EVENT_WINDOW_ENTER_FULLSCREEN or + * SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this + * is just a request, it can be denied by the windowing system. + * + * \param window the window to change. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowFullscreenMode + * \sa SDL_SetWindowFullscreenMode + * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); + +/** + * Block until any pending window state is finalized. + * + * On asynchronous windowing systems, this acts as a synchronization barrier + * for pending window state. It will attempt to wait until any pending window + * state has been applied and is guaranteed to return within finite time. Note + * that for how long it can potentially block depends on the underlying window + * system, as window state changes may involve somewhat lengthy animations + * that must complete before the window is in its final requested state. + * + * On windowing systems where changes are immediate, this does nothing. + * + * \param window the window for which to wait for the pending state to be + * applied. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowSize + * \sa SDL_SetWindowPosition + * \sa SDL_SetWindowFullscreen + * \sa SDL_MinimizeWindow + * \sa SDL_MaximizeWindow + * \sa SDL_RestoreWindow + * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); + +/** + * Return whether the window has a surface associated with it. + * + * \param window the window to query. + * \returns true if there is a surface associated with the window, or false + * otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); + +/** + * Get the SDL surface associated with the window. + * + * A new surface will be created with the optimal format for the window, if + * necessary. This surface will be freed when the window is destroyed. Do not + * free this surface. + * + * This surface will be invalidated if the window is resized. After resizing a + * window this function must be called again to return a valid surface. + * + * You may not combine this with 3D or the rendering API on this window. + * + * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`. + * + * \param window the window to query. + * \returns the surface associated with the window, or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyWindowSurface + * \sa SDL_WindowHasSurface + * \sa SDL_UpdateWindowSurface + * \sa SDL_UpdateWindowSurfaceRects + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *window); + +/** + * Toggle VSync for the window surface. + * + * When a window surface is created, vsync defaults to + * SDL_WINDOW_SURFACE_VSYNC_DISABLED. + * + * The `vsync` parameter can be 1 to synchronize present with every vertical + * refresh, 2 to synchronize present with every second vertical refresh, etc., + * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), + * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is + * supported by every driver, so you should check the return value to see + * whether the requested setting is supported. + * + * \param window the window. + * \param vsync the vertical refresh sync interval. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSurfaceVSync + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); + +#define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 +#define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) + +/** + * Get VSync for the window surface. + * + * \param window the window to query. + * \param vsync an int filled with the current vertical refresh sync interval. + * See SDL_SetWindowSurfaceVSync() for the meaning of the value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowSurfaceVSync + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); + +/** + * Copy the window surface to the screen. + * + * This is the function you use to reflect any changes to the surface on the + * screen. + * + * This function is equivalent to the SDL 1.2 API SDL_Flip(). + * + * \param window the window to update. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSurface + * \sa SDL_UpdateWindowSurfaceRects + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); + +/** + * Copy areas of the window surface to the screen. + * + * This is the function you use to reflect changes to portions of the surface + * on the screen. + * + * This function is equivalent to the SDL 1.2 API SDL_UpdateRects(). + * + * Note that this function will update _at least_ the rectangles specified, + * but this is only intended as an optimization; in practice, this might + * update more of the screen (or all of the screen!), depending on what method + * SDL uses to send pixels to the system. + * + * \param window the window to update. + * \param rects an array of SDL_Rect structures representing areas of the + * surface to copy, in pixels. + * \param numrects the number of rectangles. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSurface + * \sa SDL_UpdateWindowSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); + +/** + * Destroy the surface associated with the window. + * + * \param window the window to update. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowSurface + * \sa SDL_WindowHasSurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); + +/** + * Set a window's keyboard grab mode. + * + * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or + * the Meta/Super key. Note that not all system keyboard shortcuts can be + * captured by applications (one example is Ctrl+Alt+Del on Windows). + * + * This is primarily intended for specialized applications such as VNC clients + * or VM frontends. Normal games should not use keyboard grab. + * + * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the + * window is full-screen to ensure the user is not trapped in your + * application. If you have a custom keyboard shortcut to exit fullscreen + * mode, you may suppress this behavior with + * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`. + * + * If the caller enables a grab while another window is currently grabbed, the + * other window loses its grab in favor of the caller's window. + * + * \param window the window for which the keyboard grab mode should be set. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowKeyboardGrab + * \sa SDL_SetWindowMouseGrab + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); + +/** + * Set a window's mouse grab mode. + * + * Mouse grab confines the mouse cursor to the window. + * + * \param window the window for which the mouse grab mode should be set. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowKeyboardGrab + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); + +/** + * Get a window's keyboard grab mode. + * + * \param window the window to query. + * \returns true if keyboard is grabbed, and false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowKeyboardGrab + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); + +/** + * Get a window's mouse grab mode. + * + * \param window the window to query. + * \returns true if mouse is grabbed, and false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowKeyboardGrab + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); + +/** + * Get the window that currently has an input grab enabled. + * + * \returns the window if input is grabbed or NULL otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowMouseGrab + * \sa SDL_SetWindowKeyboardGrab + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); + +/** + * Confines the cursor to the specified area of a window. + * + * Note that this does NOT grab the cursor, it only defines the area a cursor + * is restricted to when the window has mouse focus. + * + * \param window the window that will be associated with the barrier. + * \param rect a rectangle area in window-relative coordinates. If NULL the + * barrier for the specified window will be destroyed. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); + +/** + * Get the mouse confinement rectangle of a window. + * + * \param window the window to query. + * \returns a pointer to the mouse confinement rectangle of a window, or NULL + * if there isn't one. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab + */ +extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); + +/** + * Set the opacity for a window. + * + * The parameter `opacity` will be clamped internally between 0.0f + * (transparent) and 1.0f (opaque). + * + * This function also returns false if setting the opacity isn't supported. + * + * \param window the window which will be made transparent or opaque. + * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowOpacity + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); + +/** + * Get the opacity of a window. + * + * If transparency isn't supported on this platform, opacity will be returned + * as 1.0f without error. + * + * \param window the window to get the current opacity value from. + * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowOpacity + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); + +/** + * Set the window as a child of a parent window. + * + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. + * + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. + * + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. + * + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); + +/** + * Set whether the window may have input focus. + * + * \param window the window to set focusable state. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); + + +/** + * Display the system-level window menu. + * + * This default window menu is provided by the system and on some platforms + * provides functionality for setting or changing privileged state on the + * window, such as moving it between workspaces or displays, or toggling the + * always-on-top property. + * + * On platforms or desktops where this is unsupported, this function does + * nothing. + * + * \param window the window for which the menu will be displayed. + * \param x the x coordinate of the menu, relative to the origin (top-left) of + * the client area. + * \param y the y coordinate of the menu, relative to the origin (top-left) of + * the client area. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); + +/** + * Possible return values from the SDL_HitTest callback. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_HitTest + */ +typedef enum SDL_HitTestResult +{ + SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ + SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ + SDL_HITTEST_RESIZE_TOPLEFT, /**< Region is the resizable top-left corner border. */ + SDL_HITTEST_RESIZE_TOP, /**< Region is the resizable top border. */ + SDL_HITTEST_RESIZE_TOPRIGHT, /**< Region is the resizable top-right corner border. */ + SDL_HITTEST_RESIZE_RIGHT, /**< Region is the resizable right border. */ + SDL_HITTEST_RESIZE_BOTTOMRIGHT, /**< Region is the resizable bottom-right corner border. */ + SDL_HITTEST_RESIZE_BOTTOM, /**< Region is the resizable bottom border. */ + SDL_HITTEST_RESIZE_BOTTOMLEFT, /**< Region is the resizable bottom-left corner border. */ + SDL_HITTEST_RESIZE_LEFT /**< Region is the resizable left border. */ +} SDL_HitTestResult; + +/** + * Callback used for hit-testing. + * + * \param win the SDL_Window where hit-testing was set on. + * \param area an SDL_Point which should be hit-tested. + * \param data what was passed as `callback_data` to SDL_SetWindowHitTest(). + * \returns an SDL_HitTestResult value. + * + * \sa SDL_SetWindowHitTest + */ +typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, + const SDL_Point *area, + void *data); + +/** + * Provide a callback that decides if a window region has special properties. + * + * Normally windows are dragged and resized by decorations provided by the + * system window manager (a title bar, borders, etc), but for some apps, it + * makes sense to drag them from somewhere else inside the window itself; for + * example, one might have a borderless window that wants to be draggable from + * any part, or simulate its own title bar, etc. + * + * This function lets the app provide a callback that designates pieces of a + * given window as special. This callback is run during event processing if we + * need to tell the OS to treat a region of the window specially; the use of + * this callback is known as "hit testing." + * + * Mouse input may not be delivered to your application if it is within a + * special area; the OS will often apply that input to moving the window or + * resizing the window and not deliver it to the application. + * + * Specifying NULL for a callback disables hit-testing. Hit-testing is + * disabled by default. + * + * Platforms that don't support this functionality will return false + * unconditionally, even if you're attempting to disable hit-testing. + * + * Your callback may fire at any time, and its firing does not indicate any + * specific behavior (for example, on Windows, this certainly might fire when + * the OS is deciding whether to drag your window, but it fires for lots of + * other reasons, too, some unrelated to anything you probably care about _and + * when the mouse isn't actually at the location it is testing_). Since this + * can fire at any time, you should try to keep your callback efficient, + * devoid of allocations, etc. + * + * \param window the window to set hit-testing on. + * \param callback the function to call when doing a hit-test. + * \param callback_data an app-defined void pointer passed to **callback**. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); + +/** + * Set the shape of a transparent window. + * + * This sets the alpha channel of a transparent window and any fully + * transparent areas are also transparent to mouse clicks. If you are using + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. + * + * The shape is copied inside this function, so you can free it afterwards. If + * your shape surface changes, you should call SDL_SetWindowShape() again to + * update the window. This is an expensive operation, so should be done + * sparingly. + * + * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. + * + * \param window the window. + * \param shape the surface representing the shape of the window, or NULL to + * remove any current shape. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); + +/** + * Request a window to demand attention from the user. + * + * \param window the window to be flashed. + * \param operation the operation to perform. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); + +/** + * Destroy a window. + * + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. + * + * \param window the window to destroy. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreatePopupWindow + * \sa SDL_CreateWindow + * \sa SDL_CreateWindowWithProperties + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); + + +/** + * Check whether the screensaver is currently enabled. + * + * The screensaver is disabled by default. + * + * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. + * + * \returns true if the screensaver is enabled, false if it is disabled. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DisableScreenSaver + * \sa SDL_EnableScreenSaver + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); + +/** + * Allow the screen to be blanked by a screen saver. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DisableScreenSaver + * \sa SDL_ScreenSaverEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); + +/** + * Prevent the screen from being blanked by a screen saver. + * + * If you disable the screensaver, it is automatically re-enabled when SDL + * quits. + * + * The screensaver is disabled by default, but this may by changed by + * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EnableScreenSaver + * \sa SDL_ScreenSaverEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); + + +/** + * \name OpenGL support functions + */ +/* @{ */ + +/** + * Dynamically load an OpenGL library. + * + * This should be done after initializing the video driver, but before + * creating any OpenGL windows. If no OpenGL library is loaded, the default + * library will be loaded upon creation of the first OpenGL window. + * + * If you do this, you need to retrieve all of the GL functions used in your + * program from the dynamic library using SDL_GL_GetProcAddress(). + * + * \param path the platform dependent OpenGL library name, or NULL to open the + * default OpenGL library. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_GetProcAddress + * \sa SDL_GL_UnloadLibrary + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); + +/** + * Get an OpenGL function by name. + * + * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all + * GL functions must be retrieved this way. Usually this is used to retrieve + * function pointers to OpenGL extensions. + * + * There are some quirks to looking up OpenGL functions that require some + * extra care from the application. If you code carefully, you can handle + * these quirks without any platform-specific code, though: + * + * - On Windows, function pointers are specific to the current GL context; + * this means you need to have created a GL context and made it current + * before calling SDL_GL_GetProcAddress(). If you recreate your context or + * create a second context, you should assume that any existing function + * pointers aren't valid to use with it. This is (currently) a + * Windows-specific limitation, and in practice lots of drivers don't suffer + * this limitation, but it is still the way the wgl API is documented to + * work and you should expect crashes if you don't respect it. Store a copy + * of the function pointers that comes and goes with context lifespan. + * - On X11, function pointers returned by this function are valid for any + * context, and can even be looked up before a context is created at all. + * This means that, for at least some common OpenGL implementations, if you + * look up a function that doesn't exist, you'll get a non-NULL result that + * is _NOT_ safe to call. You must always make sure the function is actually + * available for a given GL context before calling it, by checking for the + * existence of the appropriate extension with SDL_GL_ExtensionSupported(), + * or verifying that the version of OpenGL you're using offers the function + * as core functionality. + * - Some OpenGL drivers, on all platforms, *will* return NULL if a function + * isn't supported, but you can't count on this behavior. Check for + * extensions you use, and if you get a NULL anyway, act as if that + * extension wasn't available. This is probably a bug in the driver, but you + * can code defensively for this scenario anyhow. + * - Just because you're on Linux/Unix, don't assume you'll be using X11. + * Next-gen display servers are waiting to replace it, and may or may not + * make the same promises about function pointers. + * - OpenGL function pointers must be declared `APIENTRY` as in the example + * code. This will ensure the proper calling convention is followed on + * platforms where this matters (Win32) thereby avoiding stack corruption. + * + * \param proc the name of an OpenGL function. + * \returns a pointer to the named OpenGL function. The returned pointer + * should be cast to the appropriate function signature. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_ExtensionSupported + * \sa SDL_GL_LoadLibrary + * \sa SDL_GL_UnloadLibrary + */ +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char *proc); + +/** + * Get an EGL library function by name. + * + * If an EGL library is loaded, this function allows applications to get entry + * points for EGL functions. This is useful to provide to an EGL API and + * extension loader. + * + * \param proc the name of an EGL function. + * \returns a pointer to the named EGL function. The returned pointer should + * be cast to the appropriate function signature. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EGL_GetCurrentDisplay + */ +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const char *proc); + +/** + * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_LoadLibrary + */ +extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); + +/** + * Check if an OpenGL extension is supported for the current context. + * + * This function operates on the current GL context; you must have created a + * context and it must be current before calling this function. Do not assume + * that all contexts you create will have the same set of extensions + * available, or that recreating an existing context will offer the same + * extensions again. + * + * While it's probably not a massive overhead, this function is not an O(1) + * operation. Check the extensions you care about after creating the GL + * context and save that information somewhere instead of calling the function + * every time you need to know. + * + * \param extension the name of the extension to check. + * \returns true if the extension is supported, false otherwise. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); + +/** + * Reset all previously set OpenGL context attributes to their default values. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_GetAttribute + * \sa SDL_GL_SetAttribute + */ +extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); + +/** + * Set an OpenGL window attribute before window creation. + * + * This function sets the OpenGL attribute `attr` to `value`. The requested + * attributes should be set before creating an OpenGL window. You should use + * SDL_GL_GetAttribute() to check the values after creating the OpenGL + * context, since the values obtained can differ from the requested ones. + * + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to + * set. + * \param value the desired value for the attribute. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_GetAttribute + * \sa SDL_GL_ResetAttributes + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); + +/** + * Get the actual value for an attribute from the current context. + * + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to + * get. + * \param value a pointer filled in with the current value of `attr`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_ResetAttributes + * \sa SDL_GL_SetAttribute + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); + +/** + * Create an OpenGL context for an OpenGL window, and make it current. + * + * Windows users new to OpenGL should note that, for historical reasons, GL + * functions added after OpenGL version 1.1 are not available by default. + * Those functions must be loaded at run-time, either with an OpenGL + * extension-handling library or with SDL_GL_GetProcAddress() and its related + * functions. + * + * SDL_GLContext is opaque to the application. + * + * \param window the window to associate with the context. + * \returns the OpenGL context associated with `window` or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_DestroyContext + * \sa SDL_GL_MakeCurrent + */ +extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *window); + +/** + * Set up an OpenGL context for rendering into an OpenGL window. + * + * The context must have been created with a compatible window. + * + * \param window the window to associate with the context. + * \param context the OpenGL context to associate with the window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_CreateContext + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); + +/** + * Get the currently active OpenGL window. + * + * \returns the currently active OpenGL window on success or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); + +/** + * Get the currently active OpenGL context. + * + * \returns the currently active OpenGL context or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_MakeCurrent + */ +extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); + +/** + * Get the currently active EGL display. + * + * \returns the currently active EGL display or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); + +/** + * Get the currently active EGL config. + * + * \returns the currently active EGL config or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); + +/** + * Get the EGL surface associated with the window. + * + * \param window the window to query. + * \returns the EGLSurface pointer associated with the window, or NULL on + * failure. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); + +/** + * Sets the callbacks for defining custom EGLAttrib arrays for EGL + * initialization. + * + * Callbacks that aren't needed can be set to NULL. + * + * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. + * + * \param platformAttribCallback callback for attributes to pass to + * eglGetPlatformDisplay. May be NULL. + * \param surfaceAttribCallback callback for attributes to pass to + * eglCreateSurface. May be NULL. + * \param contextAttribCallback callback for attributes to pass to + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); + +/** + * Set the swap interval for the current OpenGL context. + * + * Some systems allow specifying -1 for the interval, to enable adaptive + * vsync. Adaptive vsync works the same as vsync, but if you've already missed + * the vertical retrace for a given frame, it swaps buffers immediately, which + * might be less jarring for the user during occasional framerate drops. If an + * application requests adaptive vsync and the system does not support it, + * this function will fail and return false. In such a case, you should + * probably retry the call with 1 for the interval. + * + * Adaptive vsync is implemented for some glX drivers with + * GLX_EXT_swap_control_tear, and for some Windows drivers with + * WGL_EXT_swap_control_tear. + * + * Read more on the Khronos wiki: + * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync + * + * \param interval 0 for immediate updates, 1 for updates synchronized with + * the vertical retrace, -1 for adaptive vsync. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_GetSwapInterval + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); + +/** + * Get the swap interval for the current OpenGL context. + * + * If the system can't determine the swap interval, or there isn't a valid + * current context, this function will set *interval to 0 as a safe default. + * + * \param interval output interval value. 0 if there is no vertical retrace + * synchronization, 1 if the buffer swap is synchronized with + * the vertical retrace, and -1 if late swaps happen + * immediately instead of waiting for the next retrace. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_SetSwapInterval + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); + +/** + * Update a window with OpenGL rendering. + * + * This is used with double-buffered OpenGL contexts, which are the default. + * + * On macOS, make sure you bind 0 to the draw framebuffer before swapping the + * window, otherwise nothing will happen. If you aren't using + * glBindFramebuffer(), this is the default and you won't have to do anything + * extra. + * + * \param window the window to change. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); + +/** + * Delete an OpenGL context. + * + * \param context the OpenGL context to be deleted. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GL_CreateContext + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); + +/* @} *//* OpenGL support functions */ + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_video_h_ */ diff --git a/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_vulkan.h b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_vulkan.h new file mode 100644 index 0000000000..e91e148428 --- /dev/null +++ b/code/thirdparty/SDL3-3.2.18/include/SDL3/SDL_vulkan.h @@ -0,0 +1,287 @@ +/* + Simple DirectMedia Layer + Copyright (C) 2017, Mark Callow + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryVulkan + * + * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. + */ + +#ifndef SDL_vulkan_h_ +#define SDL_vulkan_h_ + +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* Avoid including vulkan_core.h, don't define VkInstance if it's already included */ +#ifdef VULKAN_CORE_H_ +#define NO_SDL_VULKAN_TYPEDEFS +#endif +#ifndef NO_SDL_VULKAN_TYPEDEFS +#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; + +#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__)) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) || (defined(__riscv) && __riscv_xlen == 64) +#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object; +#else +#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object; +#endif + +VK_DEFINE_HANDLE(VkInstance) +VK_DEFINE_HANDLE(VkPhysicalDevice) +VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) +struct VkAllocationCallbacks; + +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + +#endif /* !NO_SDL_VULKAN_TYPEDEFS */ + +/** + * \name Vulkan support functions + */ +/* @{ */ + +/** + * Dynamically load the Vulkan loader library. + * + * This should be called after initializing the video driver, but before + * creating any Vulkan windows. If no Vulkan loader library is loaded, the + * default library will be loaded upon creation of the first Vulkan window. + * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * + * It is fairly common for Vulkan applications to link with libvulkan instead + * of explicitly loading it at run time. This will work with SDL provided the + * application links to a dynamic library and both it and SDL use the same + * search path. + * + * If you specify a non-NULL `path`, an application should retrieve all of the + * Vulkan functions it uses from the dynamic library using + * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points + * to the same vulkan loader library the application linked to. + * + * On Apple devices, if `path` is NULL, SDL will attempt to find the + * `vkGetInstanceProcAddr` address within all the Mach-O images of the current + * process. This is because it is fairly common for Vulkan applications to + * link with libvulkan (and historically MoltenVK was provided as a static + * library). If it is not found, on macOS, SDL will attempt to load + * `vulkan.framework/vulkan`, `libvulkan.1.dylib`, + * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On + * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a + * dynamic framework or .dylib must ensure it is included in its application + * bundle. + * + * On non-Apple devices, application linking with a static libvulkan is not + * supported. Either do not link to the Vulkan loader or link to a dynamic + * library version. + * + * \param path the platform dependent Vulkan loader library name or NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetVkGetInstanceProcAddr + * \sa SDL_Vulkan_UnloadLibrary + */ +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); + +/** + * Get the address of the `vkGetInstanceProcAddr` function. + * + * This should be called after either calling SDL_Vulkan_LoadLibrary() or + * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. + * + * The actual type of the returned function pointer is + * PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan + * headers are not included here. You should cast the return value of this + * function to that type, e.g. + * + * `vkGetInstanceProcAddr = + * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();` + * + * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); + +/** + * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). + * + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_LoadLibrary + */ +extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); + +/** + * Get the Vulkan instance extensions needed for vkCreateInstance. + * + * This should be called after either calling SDL_Vulkan_LoadLibrary() or + * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. + * + * On return, the variable pointed to by `count` will be set to the number of + * elements returned, suitable for using with + * VkInstanceCreateInfo::enabledExtensionCount, and the returned array can be + * used with VkInstanceCreateInfo::ppEnabledExtensionNames, for calling + * Vulkan's vkCreateInstance API. + * + * You should not free the returned array; it is owned by SDL. + * + * \param count a pointer filled in with the number of extensions returned. + * \returns an array of extension name strings on success, NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_CreateSurface + */ +extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtensions(Uint32 *count); + +/** + * Create a Vulkan rendering surface for a window. + * + * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and + * `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled. + * + * If `allocator` is NULL, Vulkan will use the system default allocator. This + * argument is passed directly to Vulkan and isn't used by SDL itself. + * + * \param window the window to which to attach the Vulkan surface. + * \param instance the Vulkan instance handle. + * \param allocator a VkAllocationCallbacks struct, which lets the app set the + * allocator that creates the surface. Can be NULL. + * \param surface a pointer to a VkSurfaceKHR handle to output the newly + * created surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + * \sa SDL_Vulkan_DestroySurface + */ +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, + VkInstance instance, + const struct VkAllocationCallbacks *allocator, + VkSurfaceKHR *surface); + +/** + * Destroy the Vulkan rendering surface of a window. + * + * This should be called before SDL_DestroyWindow, if SDL_Vulkan_CreateSurface + * was called after SDL_CreateWindow. + * + * The `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled and `surface` must have been + * created successfully by an SDL_Vulkan_CreateSurface() call. + * + * If `allocator` is NULL, Vulkan will use the system default allocator. This + * argument is passed directly to Vulkan and isn't used by SDL itself. + * + * \param instance the Vulkan instance handle. + * \param surface vkSurfaceKHR handle to destroy. + * \param allocator a VkAllocationCallbacks struct, which lets the app set the + * allocator that destroys the surface. Can be NULL. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + * \sa SDL_Vulkan_CreateSurface + */ +extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, + VkSurfaceKHR surface, + const struct VkAllocationCallbacks *allocator); + +/** + * Query support for presentation via a given physical device and queue + * family. + * + * The `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled. + * + * \param instance the Vulkan instance handle. + * \param physicalDevice a valid Vulkan physical device handle. + * \param queueFamilyIndex a valid queue family index for the given physical + * device. + * \returns true if supported, false if unsupported or an error occurred. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + */ +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, + VkPhysicalDevice physicalDevice, + Uint32 queueFamilyIndex); + +/* @} *//* Vulkan support functions */ + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_vulkan_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config.h similarity index 57% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config.h index eabd78b52a..83031b70cc 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config.h @@ -19,41 +19,39 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include -/* WIKI CATEGORY: - */ +/** + * \file SDL_build_config.h + * + * This is a set of defines to configure the SDL features + */ /* Add any platform that doesn't build using the configure system. */ -#if defined(__WIN32__) -#include "SDL_config_windows.h" -#elif defined(__WINRT__) -#include "SDL_config_winrt.h" -#elif defined(__WINGDK__) -#include "SDL_config_wingdk.h" -#elif defined(__XBOXONE__) || defined(__XBOXSERIES__) -#include "SDL_config_xbox.h" -#elif defined(__MACOSX__) -#include "SDL_config_macosx.h" -#elif defined(__IPHONEOS__) -#include "SDL_config_iphoneos.h" -#elif defined(__ANDROID__) -#include "SDL_config_android.h" -#elif defined(__OS2__) -#include "SDL_config_os2.h" -#elif defined(__EMSCRIPTEN__) -#include "SDL_config_emscripten.h" -#elif defined(__NGAGE__) -#include "SDL_config_ngage.h" +#if defined(SDL_PLATFORM_PRIVATE) +#include "SDL_build_config_private.h" +#elif defined(SDL_PLATFORM_WIN32) +#include "SDL_build_config_windows.h" +#elif defined(SDL_PLATFORM_WINGDK) +#include "SDL_build_config_wingdk.h" +#elif defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) +#include "SDL_build_config_xbox.h" +#elif defined(SDL_PLATFORM_MACOS) +#include "SDL_build_config_macos.h" +#elif defined(SDL_PLATFORM_IOS) +#include "SDL_build_config_ios.h" +#elif defined(SDL_PLATFORM_ANDROID) +#include "SDL_build_config_android.h" #else /* This is a minimal configuration just to get SDL running on new platforms. */ -#include "SDL_config_minimal.h" +#include "SDL_build_config_minimal.h" #endif /* platform config */ #ifdef USING_GENERATED_CONFIG_H -#error Wrong SDL_config.h, check your include path? +#error Wrong SDL_build_config.h, check your include path? #endif -#endif /* SDL_config_h_ */ +#endif /* SDL_build_config_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_emscripten.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_android.h similarity index 63% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_emscripten.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_android.h index 3f06490574..a0727f50cd 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_emscripten.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_android.h @@ -19,70 +19,53 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef _SDL_config_emscripten_h_ -#define _SDL_config_emscripten_h_ +#ifndef SDL_build_config_android_h_ +#define SDL_build_config_android_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /** - * \file SDL_config_emscripten.h + * \file SDL_build_config_android.h * - * This is a configuration that can be used to build SDL for Emscripten. + * This is a configuration that can be used to build SDL for Android */ -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif +#include + #define HAVE_GCC_ATOMICS 1 -/* Useful headers */ -#define STDC_HEADERS 1 #define HAVE_ALLOCA_H 1 -#define HAVE_CTYPE_H 1 -#define HAVE_ICONV_H 1 +#define HAVE_FLOAT_H 1 #define HAVE_INTTYPES_H 1 #define HAVE_LIMITS_H 1 -#define HAVE_MALLOC_H 1 #define HAVE_MATH_H 1 -#define HAVE_MEMORY_H 1 #define HAVE_SIGNAL_H 1 #define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #define HAVE_STDINT_H 1 #define HAVE_STDIO_H 1 #define HAVE_STDLIB_H 1 -#define HAVE_STRINGS_H 1 #define HAVE_STRING_H 1 #define HAVE_SYS_TYPES_H 1 #define HAVE_WCHAR_H 1 /* C library functions */ +#define HAVE_LIBC 1 #define HAVE_DLOPEN 1 #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 +#define HAVE_FDATASYNC 1 #define HAVE_GETENV 1 -#define HAVE_SETENV 1 +#define HAVE_GETHOSTNAME 1 #define HAVE_PUTENV 1 +#define HAVE_SETENV 1 #define HAVE_UNSETENV 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 #define HAVE_ABS 1 #define HAVE_BCOPY 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 #define HAVE_MEMMOVE 1 #define HAVE_MEMCMP 1 -#define HAVE_WCSLEN 1 -#define HAVE_WCSDUP 1 -#define HAVE_WCSSTR 1 -#define HAVE_WCSCMP 1 -#define HAVE_WCSNCMP 1 -#define HAVE_WCSCASECMP 1 -#define HAVE_WCSNCASECMP 1 #define HAVE_STRLEN 1 #define HAVE_STRLCPY 1 #define HAVE_STRLCAT 1 @@ -99,12 +82,8 @@ #define HAVE_ATOF 1 #define HAVE_STRCMP 1 #define HAVE_STRNCMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_SSCANF 1 #define HAVE_VSSCANF 1 #define HAVE_VSNPRINTF 1 -#define HAVE_M_PI 1 #define HAVE_ACOS 1 #define HAVE_ACOSF 1 #define HAVE_ASIN 1 @@ -127,15 +106,21 @@ #define HAVE_FLOORF 1 #define HAVE_FMOD 1 #define HAVE_FMODF 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 #define HAVE_LOG 1 #define HAVE_LOGF 1 #define HAVE_LOG10 1 #define HAVE_LOG10F 1 #define HAVE_LROUND 1 #define HAVE_LROUNDF 1 +#define HAVE_MODF 1 +#define HAVE_MODFF 1 #define HAVE_POW 1 #define HAVE_POWF 1 -#define HAVE_ROUND 1 +#define HAVE_ROUND 1 #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 #define HAVE_SCALBNF 1 @@ -147,72 +132,86 @@ #define HAVE_TANF 1 #define HAVE_TRUNC 1 #define HAVE_TRUNCF 1 -#define HAVE_FSEEKO 1 -#define HAVE_FSEEKO64 1 #define HAVE_SIGACTION 1 -#define HAVE_SA_SIGACTION 1 #define HAVE_SETJMP 1 #define HAVE_NANOSLEEP 1 +#define HAVE_GMTIME_R 1 +#define HAVE_LOCALTIME_R 1 #define HAVE_SYSCONF 1 #define HAVE_CLOCK_GETTIME 1 -/* #undef HAVE_GETPAGESIZE */ -#define HAVE_MPROTECT 1 -#define HAVE_ICONV 1 - -/* SDL internal assertion support */ -/* #undef SDL_DEFAULT_ASSERT_LEVEL */ - -#define SDL_CPUINFO_DISABLED 1 -#define SDL_HAPTIC_DISABLED 1 -#define SDL_HIDAPI_DISABLED 1 -#ifndef __EMSCRIPTEN_PTHREADS__ -#define SDL_THREADS_DISABLED 1 -#endif /* Enable various audio drivers */ -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 -#define SDL_AUDIO_DRIVER_EMSCRIPTEN 1 +#ifndef SDL_AUDIO_DISABLED +#define SDL_AUDIO_DRIVER_OPENSLES 1 +#define SDL_AUDIO_DRIVER_AAUDIO 1 +#endif /* SDL_AUDIO_DISABLED */ /* Enable various input drivers */ -#define SDL_JOYSTICK_EMSCRIPTEN 1 - -/* Enable various sensor drivers */ -#define SDL_SENSOR_DUMMY 1 +#ifndef SDL_JOYSTICK_DISABLED +#define SDL_JOYSTICK_ANDROID 1 +#define SDL_JOYSTICK_HIDAPI 1 +#define SDL_JOYSTICK_VIRTUAL 1 +#endif /* SDL_JOYSTICK_DISABLED */ +#ifndef SDL_HAPTIC_DISABLED +#define SDL_HAPTIC_ANDROID 1 +#endif /* SDL_HAPTIC_DISABLED */ + +/* Enable the stub process support */ +#define SDL_PROCESS_DUMMY 1 + +/* Enable sensor driver */ +#ifndef SDL_SENSOR_DISABLED +#define SDL_SENSOR_ANDROID 1 +#endif /* SDL_SENSOR_DISABLED */ /* Enable various shared object loading systems */ #define SDL_LOADSO_DLOPEN 1 /* Enable various threading systems */ -#ifdef __EMSCRIPTEN_PTHREADS__ #define SDL_THREAD_PTHREAD 1 #define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 -#endif + +/* Enable RTC system */ +#define SDL_TIME_UNIX 1 /* Enable various timer systems */ #define SDL_TIMER_UNIX 1 /* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_EMSCRIPTEN 1 +#define SDL_VIDEO_DRIVER_ANDROID 1 -#define SDL_VIDEO_RENDER_OGL_ES2 1 - -/* Enable OpenGL support */ -/* #undef SDL_VIDEO_OPENGL */ -/* #undef SDL_VIDEO_OPENGL_ES */ +/* Enable OpenGL ES */ +#define SDL_VIDEO_OPENGL_ES 1 #define SDL_VIDEO_OPENGL_ES2 1 -/* #undef SDL_VIDEO_OPENGL_BGL */ -/* #undef SDL_VIDEO_OPENGL_CGL */ -/* #undef SDL_VIDEO_OPENGL_GLX */ -/* #undef SDL_VIDEO_OPENGL_WGL */ #define SDL_VIDEO_OPENGL_EGL 1 -/* #undef SDL_VIDEO_OPENGL_OSMESA */ -/* #undef SDL_VIDEO_OPENGL_OSMESA_DYNAMIC */ +#define SDL_VIDEO_RENDER_OGL_ES2 1 + +/* Enable Vulkan support */ +#if defined(__ARM_ARCH) && __ARM_ARCH < 7 +/* Android does not support Vulkan in native code using the "armeabi" ABI. */ +#else +#define SDL_VIDEO_VULKAN 1 +#define SDL_VIDEO_RENDER_VULKAN 1 +#define SDL_GPU_VULKAN 1 +#define SDL_VIDEO_RENDER_GPU 1 +#endif /* Enable system power support */ -#define SDL_POWER_EMSCRIPTEN 1 +#define SDL_POWER_ANDROID 1 + +/* Enable the filesystem driver */ +#define SDL_FILESYSTEM_ANDROID 1 +#define SDL_FSOPS_POSIX 1 -/* Enable system filesystem support */ -#define SDL_FILESYSTEM_EMSCRIPTEN 1 +/* Enable the camera driver */ +#ifndef SDL_CAMERA_DISABLED +#define SDL_CAMERA_DRIVER_ANDROID 1 +#endif /* SDL_CAMERA_DISABLED */ + +/* Enable nl_langinfo and high-res file times on version 26 and higher. */ +#if __ANDROID_API__ >= 26 +#define HAVE_NL_LANGINFO 1 +#define HAVE_ST_MTIM 1 +#endif -#endif /* _SDL_config_emscripten_h_ */ +#endif /* SDL_build_config_android_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_iphoneos.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_ios.h similarity index 52% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_iphoneos.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_ios.h index fed314e8bd..be1ec29a18 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_iphoneos.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_ios.h @@ -19,129 +19,125 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_iphoneos_h_ -#define SDL_config_iphoneos_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_ios_h_ +#define SDL_build_config_ios_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -#define HAVE_GCC_ATOMICS 1 +#define HAVE_GCC_ATOMICS 1 -#define STDC_HEADERS 1 -#define HAVE_ALLOCA_H 1 -#define HAVE_CTYPE_H 1 +#define HAVE_ALLOCA_H 1 +#define HAVE_FLOAT_H 1 #define HAVE_INTTYPES_H 1 -#define HAVE_LIMITS_H 1 +#define HAVE_LIMITS_H 1 #define HAVE_MATH_H 1 -#define HAVE_SIGNAL_H 1 -#define HAVE_STDINT_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STRING_H 1 -#define HAVE_SYS_TYPES_H 1 -/* The libunwind functions are only available on x86 */ -/* #undef HAVE_LIBUNWIND_H */ +#define HAVE_SIGNAL_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 +#define HAVE_STDINT_H 1 +#define HAVE_STDIO_H 1 +#define HAVE_STDLIB_H 1 +#define HAVE_STRING_H 1 +#define HAVE_SYS_TYPES_H 1 +#define HAVE_WCHAR_H 1 /* C library functions */ +#define HAVE_LIBC 1 #define HAVE_DLOPEN 1 #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 #define HAVE_GETENV 1 -#define HAVE_SETENV 1 +#define HAVE_GETHOSTNAME 1 #define HAVE_PUTENV 1 #define HAVE_SETENV 1 -#define HAVE_UNSETENV 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#define HAVE_ABS 1 -#define HAVE_BCOPY 1 +#define HAVE_UNSETENV 1 +#define HAVE_ABS 1 +#define HAVE_BCOPY 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 +#define HAVE_MEMMOVE 1 #define HAVE_MEMCMP 1 #define HAVE_STRLEN 1 -#define HAVE_STRLCPY 1 -#define HAVE_STRLCAT 1 +#define HAVE_STRLCPY 1 +#define HAVE_STRLCAT 1 #define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 +#define HAVE_STRRCHR 1 #define HAVE_STRSTR 1 #define HAVE_STRTOK_R 1 #define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 +#define HAVE_STRTOUL 1 +#define HAVE_STRTOLL 1 +#define HAVE_STRTOULL 1 #define HAVE_STRTOD 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 +#define HAVE_ATOI 1 +#define HAVE_ATOF 1 #define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_STRCASESTR 1 +#define HAVE_STRNCMP 1 +#define HAVE_STRPBRK 1 #define HAVE_VSSCANF 1 -#define HAVE_VSNPRINTF 1 -#define HAVE_M_PI 1 -#define HAVE_ACOS 1 -#define HAVE_ACOSF 1 -#define HAVE_ASIN 1 -#define HAVE_ASINF 1 -#define HAVE_ATAN 1 -#define HAVE_ATANF 1 -#define HAVE_ATAN2 1 +#define HAVE_VSNPRINTF 1 +#define HAVE_ACOS 1 +#define HAVE_ACOSF 1 +#define HAVE_ASIN 1 +#define HAVE_ASINF 1 +#define HAVE_ATAN 1 +#define HAVE_ATANF 1 +#define HAVE_ATAN2 1 #define HAVE_ATAN2F 1 -#define HAVE_CEIL 1 -#define HAVE_CEILF 1 -#define HAVE_COPYSIGN 1 -#define HAVE_COPYSIGNF 1 -#define HAVE_COS 1 -#define HAVE_COSF 1 -#define HAVE_EXP 1 -#define HAVE_EXPF 1 -#define HAVE_FABS 1 -#define HAVE_FABSF 1 -#define HAVE_FLOOR 1 +#define HAVE_CEIL 1 +#define HAVE_CEILF 1 +#define HAVE_COPYSIGN 1 +#define HAVE_COPYSIGNF 1 +#define HAVE_COS 1 +#define HAVE_COSF 1 +#define HAVE_EXP 1 +#define HAVE_EXPF 1 +#define HAVE_FABS 1 +#define HAVE_FABSF 1 +#define HAVE_FLOOR 1 #define HAVE_FLOORF 1 -#define HAVE_FMOD 1 -#define HAVE_FMODF 1 -#define HAVE_LOG 1 -#define HAVE_LOGF 1 -#define HAVE_LOG10 1 +#define HAVE_FMOD 1 +#define HAVE_FMODF 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 +#define HAVE_LOG 1 +#define HAVE_LOGF 1 +#define HAVE_LOG10 1 #define HAVE_LOG10F 1 #define HAVE_LROUND 1 #define HAVE_LROUNDF 1 -#define HAVE_POW 1 -#define HAVE_POWF 1 -#define HAVE_ROUND 1 +#define HAVE_MODF 1 +#define HAVE_MODFF 1 +#define HAVE_POW 1 +#define HAVE_POWF 1 +#define HAVE_ROUND 1 #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 -#define HAVE_SCALBNF 1 -#define HAVE_SIN 1 -#define HAVE_SINF 1 -#define HAVE_SQRT 1 -#define HAVE_SQRTF 1 -#define HAVE_TAN 1 -#define HAVE_TANF 1 -#define HAVE_TRUNC 1 +#define HAVE_SCALBNF 1 +#define HAVE_SIN 1 +#define HAVE_SINF 1 +#define HAVE_SQRT 1 +#define HAVE_SQRTF 1 +#define HAVE_TAN 1 +#define HAVE_TANF 1 +#define HAVE_TRUNC 1 #define HAVE_TRUNCF 1 -#define HAVE_SIGACTION 1 +#define HAVE_SIGACTION 1 #define HAVE_SETJMP 1 -#define HAVE_NANOSLEEP 1 -#define HAVE_SYSCONF 1 +#define HAVE_NANOSLEEP 1 +#define HAVE_GMTIME_R 1 +#define HAVE_LOCALTIME_R 1 +#define HAVE_NL_LANGINFO 1 +#define HAVE_SYSCONF 1 #define HAVE_SYSCTLBYNAME 1 #define HAVE_O_CLOEXEC 1 /* enable iPhone version of Core Audio driver */ #define SDL_AUDIO_DRIVER_COREAUDIO 1 /* Enable the dummy audio driver (src/audio/dummy/\*.c) */ -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable the stub haptic driver (src/haptic/dummy/\*.c) */ #define SDL_HAPTIC_DUMMY 1 @@ -150,56 +146,58 @@ /* Only enable HIDAPI support if you want to support Steam Controllers on iOS and tvOS */ /*#define SDL_JOYSTICK_HIDAPI 1*/ #define SDL_JOYSTICK_MFI 1 -#define SDL_JOYSTICK_VIRTUAL 1 +#define SDL_JOYSTICK_VIRTUAL 1 + +/* Enable various process implementations */ +#define SDL_PROCESS_DUMMY 1 -#ifdef __TVOS__ -#define SDL_SENSOR_DUMMY 1 +#ifdef SDL_PLATFORM_TVOS +#define SDL_SENSOR_DUMMY 1 #else /* Enable the CoreMotion sensor driver */ -#define SDL_SENSOR_COREMOTION 1 +#define SDL_SENSOR_COREMOTION 1 #endif /* Enable Unix style SO loading */ #define SDL_LOADSO_DLOPEN 1 /* Enable various threading systems */ -#define SDL_THREAD_PTHREAD 1 -#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 +#define SDL_THREAD_PTHREAD 1 +#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 + +/* Enable various RTC system */ +#define SDL_TIME_UNIX 1 /* Enable various timer systems */ -#define SDL_TIMER_UNIX 1 +#define SDL_TIMER_UNIX 1 /* Supported video drivers */ -#define SDL_VIDEO_DRIVER_UIKIT 1 -#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_UIKIT 1 +#define SDL_VIDEO_DRIVER_DUMMY 1 /* Enable OpenGL ES */ -#if !TARGET_OS_MACCATALYST +#if !TARGET_OS_MACCATALYST && !TARGET_OS_VISION #define SDL_VIDEO_OPENGL_ES2 1 #define SDL_VIDEO_OPENGL_ES 1 -#define SDL_VIDEO_RENDER_OGL_ES 1 -#define SDL_VIDEO_RENDER_OGL_ES2 1 +#define SDL_VIDEO_RENDER_OGL_ES2 1 #endif /* Metal supported on 64-bit devices running iOS 8.0 and tvOS 9.0 and newer Also supported in simulator from iOS 13.0 and tvOS 13.0 */ #if (TARGET_OS_SIMULATOR && ((__IPHONE_OS_VERSION_MIN_REQUIRED >= 130000) || (__TV_OS_VERSION_MIN_REQUIRED >= 130000))) || (!TARGET_CPU_ARM && ((__IPHONE_OS_VERSION_MIN_REQUIRED >= 80000) || (__TV_OS_VERSION_MIN_REQUIRED >= 90000))) -#define SDL_PLATFORM_SUPPORTS_METAL 1 +#define SDL_PLATFORM_SUPPORTS_METAL 1 #else -#define SDL_PLATFORM_SUPPORTS_METAL 0 -#endif - -#if SDL_PLATFORM_SUPPORTS_METAL -#define SDL_VIDEO_RENDER_METAL 1 -#endif - -#if SDL_PLATFORM_SUPPORTS_METAL -#define SDL_VIDEO_VULKAN 1 +#define SDL_PLATFORM_SUPPORTS_METAL 0 #endif #if SDL_PLATFORM_SUPPORTS_METAL #define SDL_VIDEO_METAL 1 +#define SDL_VIDEO_VULKAN 1 +#define SDL_GPU_METAL 1 +#define SDL_GPU_VULKAN 1 +#define SDL_VIDEO_RENDER_METAL 1 +#define SDL_VIDEO_RENDER_GPU 1 #endif /* Enable system power support */ @@ -212,6 +210,17 @@ #define SDL_IPHONE_LAUNCHSCREEN 1 /* enable filesystem support */ -#define SDL_FILESYSTEM_COCOA 1 +#define SDL_FILESYSTEM_COCOA 1 +#define SDL_FSOPS_POSIX 1 + +/* enable camera support */ +#ifndef SDL_PLATFORM_TVOS +#define SDL_CAMERA_DRIVER_COREMEDIA 1 +#endif + +#define SDL_CAMERA_DRIVER_DUMMY 1 + +/* Enable dialog subsystem */ +#define SDL_DIALOG_DUMMY 1 -#endif /* SDL_config_iphoneos_h_ */ +#endif /* SDL_build_config_ios_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_macosx.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_macos.h similarity index 51% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_macosx.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_macos.h index e9e6b6d328..1a66449ac6 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_macosx.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_macos.h @@ -19,130 +19,127 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_macosx_h_ -#define SDL_config_macosx_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_macos_h_ +#define SDL_build_config_macos_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /* This gets us MAC_OS_X_VERSION_MIN_REQUIRED... */ #include /* This is a set of defines to configure the SDL features */ -#ifdef __LP64__ - #define SIZEOF_VOIDP 8 -#else - #define SIZEOF_VOIDP 4 -#endif - /* Useful headers */ -#define STDC_HEADERS 1 -#define HAVE_ALLOCA_H 1 -#define HAVE_CTYPE_H 1 -#define HAVE_FLOAT_H 1 +#define HAVE_ALLOCA_H 1 +#define HAVE_FLOAT_H 1 #define HAVE_INTTYPES_H 1 -#define HAVE_LIMITS_H 1 +#define HAVE_LIMITS_H 1 #define HAVE_MATH_H 1 -#define HAVE_SIGNAL_H 1 -#define HAVE_STDINT_H 1 -#define HAVE_STDIO_H 1 -#define HAVE_STRING_H 1 -#define HAVE_SYS_TYPES_H 1 -#define HAVE_LIBUNWIND_H 1 +#define HAVE_SIGNAL_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 +#define HAVE_STDINT_H 1 +#define HAVE_STDIO_H 1 +#define HAVE_STDLIB_H 1 +#define HAVE_STRING_H 1 +#define HAVE_SYS_TYPES_H 1 +#define HAVE_WCHAR_H 1 /* C library functions */ +#define HAVE_LIBC 1 #define HAVE_DLOPEN 1 #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 #define HAVE_GETENV 1 +#define HAVE_GETHOSTNAME 1 #define HAVE_SETENV 1 #define HAVE_PUTENV 1 -#define HAVE_UNSETENV 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#define HAVE_ABS 1 -#define HAVE_BCOPY 1 +#define HAVE_UNSETENV 1 +#define HAVE_ABS 1 +#define HAVE_BCOPY 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 -#define HAVE_MEMMOVE 1 +#define HAVE_MEMMOVE 1 #define HAVE_MEMCMP 1 #define HAVE_STRLEN 1 -#define HAVE_STRLCPY 1 -#define HAVE_STRLCAT 1 +#define HAVE_STRLCPY 1 +#define HAVE_STRLCAT 1 +#define HAVE_STRPBRK 1 #define HAVE_STRCHR 1 -#define HAVE_STRRCHR 1 +#define HAVE_STRRCHR 1 #define HAVE_STRSTR 1 #define HAVE_STRTOK_R 1 #define HAVE_STRTOL 1 -#define HAVE_STRTOUL 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 +#define HAVE_STRTOUL 1 +#define HAVE_STRTOLL 1 +#define HAVE_STRTOULL 1 #define HAVE_STRTOD 1 -#define HAVE_ATOI 1 -#define HAVE_ATOF 1 +#define HAVE_ATOI 1 +#define HAVE_ATOF 1 #define HAVE_STRCMP 1 -#define HAVE_STRNCMP 1 -#define HAVE_STRCASECMP 1 -#define HAVE_STRNCASECMP 1 -#define HAVE_STRCASESTR 1 +#define HAVE_STRNCMP 1 #define HAVE_VSSCANF 1 -#define HAVE_VSNPRINTF 1 -#define HAVE_M_PI 1 -#define HAVE_ACOS 1 -#define HAVE_ACOSF 1 -#define HAVE_ASIN 1 -#define HAVE_ASINF 1 -#define HAVE_ATAN 1 -#define HAVE_ATANF 1 -#define HAVE_ATAN2 1 +#define HAVE_VSNPRINTF 1 +#define HAVE_ACOS 1 +#define HAVE_ACOSF 1 +#define HAVE_ASIN 1 +#define HAVE_ASINF 1 +#define HAVE_ATAN 1 +#define HAVE_ATANF 1 +#define HAVE_ATAN2 1 #define HAVE_ATAN2F 1 -#define HAVE_CEIL 1 -#define HAVE_CEILF 1 -#define HAVE_COPYSIGN 1 -#define HAVE_COPYSIGNF 1 -#define HAVE_COS 1 -#define HAVE_COSF 1 -#define HAVE_EXP 1 -#define HAVE_EXPF 1 -#define HAVE_FABS 1 -#define HAVE_FABSF 1 -#define HAVE_FLOOR 1 +#define HAVE_CEIL 1 +#define HAVE_CEILF 1 +#define HAVE_COPYSIGN 1 +#define HAVE_COPYSIGNF 1 +#define HAVE_COS 1 +#define HAVE_COSF 1 +#define HAVE_EXP 1 +#define HAVE_EXPF 1 +#define HAVE_FABS 1 +#define HAVE_FABSF 1 +#define HAVE_FLOOR 1 #define HAVE_FLOORF 1 -#define HAVE_FMOD 1 -#define HAVE_FMODF 1 -#define HAVE_LOG 1 -#define HAVE_LOGF 1 -#define HAVE_LOG10 1 +#define HAVE_FMOD 1 +#define HAVE_FMODF 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 +#define HAVE_LOG 1 +#define HAVE_LOGF 1 +#define HAVE_LOG10 1 #define HAVE_LOG10F 1 #define HAVE_LROUND 1 #define HAVE_LROUNDF 1 -#define HAVE_POW 1 -#define HAVE_POWF 1 -#define HAVE_ROUND 1 +#define HAVE_MODF 1 +#define HAVE_MODFF 1 +#define HAVE_POW 1 +#define HAVE_POWF 1 +#define HAVE_ROUND 1 #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 -#define HAVE_SCALBNF 1 -#define HAVE_SIN 1 -#define HAVE_SINF 1 -#define HAVE_SQRT 1 -#define HAVE_SQRTF 1 -#define HAVE_TAN 1 -#define HAVE_TANF 1 -#define HAVE_TRUNC 1 -#define HAVE_TRUNCF 1 -#define HAVE_SIGACTION 1 +#define HAVE_SCALBNF 1 +#define HAVE_SIN 1 +#define HAVE_SINF 1 +#define HAVE_SQRT 1 +#define HAVE_SQRTF 1 +#define HAVE_TAN 1 +#define HAVE_TANF 1 +#define HAVE_TRUNC 1 +#define HAVE_TRUNCF 1 +#define HAVE_SIGACTION 1 #define HAVE_SETJMP 1 -#define HAVE_NANOSLEEP 1 -#define HAVE_SYSCONF 1 +#define HAVE_NANOSLEEP 1 +#define HAVE_GMTIME_R 1 +#define HAVE_LOCALTIME_R 1 +#define HAVE_NL_LANGINFO 1 +#define HAVE_SYSCONF 1 #define HAVE_SYSCTLBYNAME 1 #if defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 +# if !__has_include() +# define SDL_DISABLE_AVX 1 # endif #endif @@ -153,37 +150,44 @@ #define HAVE_GCC_ATOMICS 1 /* Enable various audio drivers */ -#define SDL_AUDIO_DRIVER_COREAUDIO 1 -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_COREAUDIO 1 +#define SDL_AUDIO_DRIVER_DISK 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable various input drivers */ #define SDL_JOYSTICK_HIDAPI 1 -#define SDL_JOYSTICK_IOKIT 1 -#define SDL_JOYSTICK_VIRTUAL 1 -#define SDL_HAPTIC_IOKIT 1 +#define SDL_JOYSTICK_IOKIT 1 +#define SDL_JOYSTICK_VIRTUAL 1 +#define SDL_HAPTIC_IOKIT 1 /* The MFI controller support requires ARC Objective C runtime */ #if MAC_OS_X_VERSION_MIN_REQUIRED >= 1080 && !defined(__i386__) #define SDL_JOYSTICK_MFI 1 #endif +/* Enable various process implementations */ +#define SDL_PROCESS_POSIX 1 + /* Enable the dummy sensor driver */ -#define SDL_SENSOR_DUMMY 1 +#define SDL_SENSOR_DUMMY 1 /* Enable various shared object loading systems */ -#define SDL_LOADSO_DLOPEN 1 +#define SDL_LOADSO_DLOPEN 1 /* Enable various threading systems */ -#define SDL_THREAD_PTHREAD 1 -#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 +#define SDL_THREAD_PTHREAD 1 +#define SDL_THREAD_PTHREAD_RECURSIVE_MUTEX 1 + +/* Enable various RTC system */ +#define SDL_TIME_UNIX 1 /* Enable various timer systems */ -#define SDL_TIMER_UNIX 1 +#define SDL_TIMER_UNIX 1 /* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_COCOA 1 -#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_COCOA 1 +#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_OFFSCREEN 1 #undef SDL_VIDEO_DRIVER_X11 #define SDL_VIDEO_DRIVER_X11_DYNAMIC "/opt/X11/lib/libX11.6.dylib" #define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/opt/X11/lib/libXext.6.dylib" @@ -194,7 +198,7 @@ #define SDL_VIDEO_DRIVER_X11_XRANDR 1 #define SDL_VIDEO_DRIVER_X11_XSCRNSAVER 1 #define SDL_VIDEO_DRIVER_X11_XSHAPE 1 -#define SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM 1 +#define SDL_VIDEO_DRIVER_X11_HAS_XKBLOOKUPKEYSYM 1 #ifdef MAC_OS_X_VERSION_10_8 /* @@ -206,72 +210,48 @@ #define SDL_VIDEO_DRIVER_X11_SUPPORTS_GENERIC_EVENTS 1 #endif -#ifndef SDL_VIDEO_RENDER_OGL -#define SDL_VIDEO_RENDER_OGL 1 -#endif - -#ifndef SDL_VIDEO_RENDER_OGL_ES2 +#define SDL_VIDEO_RENDER_OGL 1 #define SDL_VIDEO_RENDER_OGL_ES2 1 -#endif /* Metal only supported on 64-bit architectures with 10.11+ */ #if TARGET_RT_64_BIT && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100) -#define SDL_PLATFORM_SUPPORTS_METAL 1 -#else -#define SDL_PLATFORM_SUPPORTS_METAL 0 +#define SDL_PLATFORM_SUPPORTS_METAL 1 #endif -#ifndef SDL_VIDEO_RENDER_METAL -#if SDL_PLATFORM_SUPPORTS_METAL -#define SDL_VIDEO_RENDER_METAL 1 -#else -#define SDL_VIDEO_RENDER_METAL 0 -#endif +#ifdef SDL_PLATFORM_SUPPORTS_METAL +#define SDL_VIDEO_RENDER_METAL 1 #endif /* Enable OpenGL support */ -#ifndef SDL_VIDEO_OPENGL -#define SDL_VIDEO_OPENGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_ES2 -#define SDL_VIDEO_OPENGL_ES2 1 -#endif -#ifndef SDL_VIDEO_OPENGL_EGL -#define SDL_VIDEO_OPENGL_EGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_CGL -#define SDL_VIDEO_OPENGL_CGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_GLX -#define SDL_VIDEO_OPENGL_GLX 1 -#endif +#define SDL_VIDEO_OPENGL 1 +#define SDL_VIDEO_OPENGL_ES2 1 +#define SDL_VIDEO_OPENGL_EGL 1 +#define SDL_VIDEO_OPENGL_CGL 1 +#define SDL_VIDEO_OPENGL_GLX 1 /* Enable Vulkan and Metal support */ -#ifndef SDL_VIDEO_VULKAN -#if SDL_PLATFORM_SUPPORTS_METAL -#define SDL_VIDEO_VULKAN 1 -#else -#define SDL_VIDEO_VULKAN 0 -#endif -#endif - -#ifndef SDL_VIDEO_METAL -#if SDL_PLATFORM_SUPPORTS_METAL +#ifdef SDL_PLATFORM_SUPPORTS_METAL #define SDL_VIDEO_METAL 1 -#else -#define SDL_VIDEO_METAL 0 -#endif +#define SDL_GPU_METAL 1 +#define SDL_VIDEO_VULKAN 1 +#define SDL_GPU_VULKAN 1 +#define SDL_VIDEO_RENDER_GPU 1 #endif /* Enable system power support */ #define SDL_POWER_MACOSX 1 /* enable filesystem support */ -#define SDL_FILESYSTEM_COCOA 1 +#define SDL_FILESYSTEM_COCOA 1 +#define SDL_FSOPS_POSIX 1 + +/* enable camera support */ +#define SDL_CAMERA_DRIVER_COREMEDIA 1 +#define SDL_CAMERA_DRIVER_DUMMY 1 /* Enable assembly routines */ #ifdef __ppc__ -#define SDL_ALTIVEC_BLITTERS 1 +#define SDL_ALTIVEC_BLITTERS 1 #endif -#endif /* SDL_config_macosx_h_ */ +#endif /* SDL_build_config_macos_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_minimal.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_minimal.h similarity index 75% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_minimal.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_minimal.h index 5695871787..d5fe736e9d 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_minimal.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_minimal.h @@ -19,20 +19,20 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_minimal_h_ -#define SDL_config_minimal_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_minimal_h_ +#define SDL_build_config_minimal_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /** - * \file SDL_config_minimal.h + * \file SDL_build_config_minimal.h * * This is the minimal configuration that can be used to build SDL. */ -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #if !defined(HAVE_STDINT_H) && !defined(_STDINT_H_) /* Most everything except Visual Studio 2008 and earlier has stdint.h now */ @@ -51,7 +51,6 @@ typedef unsigned __int64 uintptr_t; #else typedef unsigned int uintptr_t; #endif -#define _UINTPTR_T_DEFINED #endif #else #define HAVE_STDINT_H 1 @@ -63,10 +62,10 @@ typedef unsigned int uintptr_t; #endif /* Enable the dummy audio driver (src/audio/dummy/\*.c) */ -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable the stub joystick driver (src/joystick/dummy/\*.c) */ -#define SDL_JOYSTICK_DISABLED 1 +#define SDL_JOYSTICK_DISABLED 1 /* Enable the stub haptic driver (src/haptic/dummy/\*.c) */ #define SDL_HAPTIC_DISABLED 1 @@ -74,22 +73,29 @@ typedef unsigned int uintptr_t; /* Enable the stub HIDAPI */ #define SDL_HIDAPI_DISABLED 1 +/* Enable the stub process support */ +#define SDL_PROCESS_DUMMY 1 + /* Enable the stub sensor driver (src/sensor/dummy/\*.c) */ #define SDL_SENSOR_DISABLED 1 -/* Enable the stub shared object loader (src/loadso/dummy/\*.c) */ -#define SDL_LOADSO_DISABLED 1 +/* Enable the dummy shared object loader (src/loadso/dummy/\*.c) */ +#define SDL_LOADSO_DUMMY 1 /* Enable the stub thread support (src/thread/generic/\*.c) */ -#define SDL_THREADS_DISABLED 1 - -/* Enable the stub timer support (src/timer/dummy/\*.c) */ -#define SDL_TIMERS_DISABLED 1 +#define SDL_THREADS_DISABLED 1 /* Enable the dummy video driver (src/video/dummy/\*.c) */ -#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_DUMMY 1 /* Enable the dummy filesystem driver (src/filesystem/dummy/\*.c) */ -#define SDL_FILESYSTEM_DUMMY 1 +#define SDL_FILESYSTEM_DUMMY 1 +#define SDL_FSOPS_DUMMY 1 + +/* Enable the camera driver (src/camera/dummy/\*.c) */ +#define SDL_CAMERA_DRIVER_DUMMY 1 + +/* Enable dialog subsystem */ +#define SDL_DIALOG_DUMMY 1 -#endif /* SDL_config_minimal_h_ */ +#endif /* SDL_build_config_minimal_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_windows.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_windows.h similarity index 62% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_windows.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_windows.h index 77d2d74fd1..4427517641 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_windows.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_windows.h @@ -19,11 +19,11 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_windows_h_ -#define SDL_config_windows_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_windows_h_ +#define SDL_build_config_windows_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /* winsdkver.h defines _WIN32_MAXVER for SDK version detection. It is present since at least the Windows 7 SDK, * but out of caution we'll only use it if the compiler supports __has_include() to confirm its presence. @@ -69,19 +69,12 @@ typedef unsigned __int64 uintptr_t; #else typedef unsigned int uintptr_t; #endif -#define _UINTPTR_T_DEFINED #endif #else #define HAVE_STDINT_H 1 #endif /* Visual Studio 2008 */ #endif /* !_STDINT_H_ && !HAVE_STDINT_H */ -#ifdef _WIN64 -# define SIZEOF_VOIDP 8 -#else -# define SIZEOF_VOIDP 4 -#endif - #ifdef __clang__ # define HAVE_GCC_ATOMICS 1 #endif @@ -89,21 +82,16 @@ typedef unsigned int uintptr_t; #define HAVE_DDRAW_H 1 #define HAVE_DINPUT_H 1 #define HAVE_DSOUND_H 1 -#ifndef __WATCOMC__ #define HAVE_DXGI_H 1 #define HAVE_XINPUT_H 1 #if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0A00 /* Windows 10 SDK */ +#define HAVE_DXGI1_6_H 1 #define HAVE_WINDOWS_GAMING_INPUT_H 1 #endif #if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0602 /* Windows 8 SDK */ #define HAVE_D3D11_H 1 #define HAVE_ROAPI_H 1 #endif -#if defined(__has_include) -#if __has_include() && __has_include() -#define HAVE_D3D12_H 1 -#endif -#endif #if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0603 /* Windows 8.1 SDK */ #define HAVE_SHELLSCALINGAPI_H 1 #endif @@ -111,38 +99,38 @@ typedef unsigned int uintptr_t; #define HAVE_AUDIOCLIENT_H 1 #define HAVE_TPCSHRD_H 1 #define HAVE_SENSORSAPI_H 1 +#if defined(__has_include) && __has_include() +#define HAVE_GAMEINPUT_H 1 #endif #if (defined(_M_IX86) || defined(_M_X64) || defined(_M_AMD64)) && (defined(_MSC_VER) && _MSC_VER >= 1600) -#define HAVE_IMMINTRIN_H 1 #elif defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 +# if !__has_include() +# define SDL_DISABLE_AVX 1 # endif +#else +# define SDL_DISABLE_AVX 1 +#endif + +/* This can be disabled to avoid C runtime dependencies and manifest requirements */ +#ifndef HAVE_LIBC +#define HAVE_LIBC 1 #endif -/* This is disabled by default to avoid C runtime dependencies and manifest requirements */ -#ifdef HAVE_LIBC +#if HAVE_LIBC /* Useful headers */ -#define STDC_HEADERS 1 -#define HAVE_CTYPE_H 1 #define HAVE_FLOAT_H 1 #define HAVE_LIMITS_H 1 #define HAVE_MATH_H 1 #define HAVE_SIGNAL_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #define HAVE_STDIO_H 1 +#define HAVE_STDLIB_H 1 #define HAVE_STRING_H 1 +#define HAVE_WCHAR_H 1 /* C library functions */ #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -/* OpenWatcom requires specific calling conventions for qsort and bsearch */ -#ifndef __WATCOMC__ -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 -#endif #define HAVE_ABS 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 @@ -150,9 +138,6 @@ typedef unsigned int uintptr_t; #define HAVE_MEMCMP 1 #define HAVE_STRLEN 1 #define HAVE__STRREV 1 -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__STRUPR */ -/* #undef HAVE__STRLWR */ #define HAVE_STRCHR 1 #define HAVE_STRRCHR 1 #define HAVE_STRSTR 1 @@ -167,47 +152,47 @@ typedef unsigned int uintptr_t; #define HAVE_ATOF 1 #define HAVE_STRCMP 1 #define HAVE_STRNCMP 1 -#define HAVE__STRICMP 1 -#define HAVE__STRNICMP 1 -#define HAVE__WCSICMP 1 -#define HAVE__WCSNICMP 1 -#define HAVE__WCSDUP 1 -#define HAVE_ACOS 1 -#define HAVE_ASIN 1 -#define HAVE_ATAN 1 -#define HAVE_ATAN2 1 -#define HAVE_CEIL 1 -#define HAVE_COS 1 -#define HAVE_EXP 1 -#define HAVE_FABS 1 -#define HAVE_FLOOR 1 -#define HAVE_FMOD 1 -#define HAVE_LOG 1 -#define HAVE_LOG10 1 -#define HAVE_POW 1 -#define HAVE_SIN 1 -#define HAVE_SQRT 1 -#define HAVE_TAN 1 -#ifndef __WATCOMC__ -#define HAVE_ACOSF 1 -#define HAVE_ASINF 1 -#define HAVE_ATANF 1 +#define HAVE_STRPBRK 1 +#define HAVE_VSSCANF 1 +#define HAVE_VSNPRINTF 1 +#define HAVE_ACOS 1 +#define HAVE_ASIN 1 +#define HAVE_ATAN 1 +#define HAVE_ATAN2 1 +#define HAVE_CEIL 1 +#define HAVE_COS 1 +#define HAVE_EXP 1 +#define HAVE_FABS 1 +#define HAVE_FLOOR 1 +#define HAVE_FMOD 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 +#define HAVE_LOG 1 +#define HAVE_LOG10 1 +#define HAVE_POW 1 +#define HAVE_SIN 1 +#define HAVE_SQRT 1 +#define HAVE_TAN 1 +#define HAVE_ACOSF 1 +#define HAVE_ASINF 1 +#define HAVE_ATANF 1 #define HAVE_ATAN2F 1 -#define HAVE_CEILF 1 +#define HAVE_CEILF 1 #define HAVE__COPYSIGN 1 -#define HAVE_COSF 1 -#define HAVE_EXPF 1 -#define HAVE_FABSF 1 +#define HAVE_COSF 1 +#define HAVE_EXPF 1 +#define HAVE_FABSF 1 #define HAVE_FLOORF 1 -#define HAVE_FMODF 1 -#define HAVE_LOGF 1 +#define HAVE_FMODF 1 +#define HAVE_LOGF 1 #define HAVE_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#endif -#if defined(_MSC_VER) +#define HAVE_POWF 1 +#define HAVE_SINF 1 +#define HAVE_SQRTF 1 +#define HAVE_TANF 1 +#ifdef _MSC_VER /* These functions were added with the VC++ 2013 C runtime library */ #if _MSC_VER >= 1800 #define HAVE_STRTOLL 1 @@ -219,30 +204,17 @@ typedef unsigned int uintptr_t; #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 #define HAVE_SCALBNF 1 -#define HAVE_TRUNC 1 +#define HAVE_TRUNC 1 #define HAVE_TRUNCF 1 #endif /* This function is available with at least the VC++ 2008 C runtime library */ #if _MSC_VER >= 1400 #define HAVE__FSEEKI64 1 #endif -#ifdef _USE_MATH_DEFINES -#define HAVE_M_PI 1 -#endif -#elif defined(__WATCOMC__) -#define HAVE__FSEEKI64 1 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_VSSCANF 1 -#define HAVE_ROUND 1 -#define HAVE_SCALBN 1 -#define HAVE_TRUNC 1 +#endif /* _MSC_VER */ #else -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #endif /* Enable various audio drivers */ @@ -250,84 +222,86 @@ typedef unsigned int uintptr_t; #define SDL_AUDIO_DRIVER_WASAPI 1 #endif #define SDL_AUDIO_DRIVER_DSOUND 1 -#define SDL_AUDIO_DRIVER_WINMM 1 -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_DISK 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable various input drivers */ #define SDL_JOYSTICK_DINPUT 1 -#define SDL_JOYSTICK_HIDAPI 1 -#ifndef __WINRT__ -#define SDL_JOYSTICK_RAWINPUT 1 +#ifdef HAVE_GAMEINPUT_H +#define SDL_JOYSTICK_GAMEINPUT 1 #endif -#define SDL_JOYSTICK_VIRTUAL 1 +#define SDL_JOYSTICK_HIDAPI 1 +#define SDL_JOYSTICK_RAWINPUT 1 +#define SDL_JOYSTICK_VIRTUAL 1 #ifdef HAVE_WINDOWS_GAMING_INPUT_H -#define SDL_JOYSTICK_WGI 1 +#define SDL_JOYSTICK_WGI 1 #endif #define SDL_JOYSTICK_XINPUT 1 -#define SDL_HAPTIC_DINPUT 1 -#define SDL_HAPTIC_XINPUT 1 +#define SDL_HAPTIC_DINPUT 1 + +/* Enable various process implementations */ +#define SDL_PROCESS_WINDOWS 1 /* Enable the sensor driver */ #ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 +#define SDL_SENSOR_WINDOWS 1 #else -#define SDL_SENSOR_DUMMY 1 +#define SDL_SENSOR_DUMMY 1 #endif /* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 +#define SDL_LOADSO_WINDOWS 1 /* Enable various threading systems */ #define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 +#define SDL_THREAD_GENERIC_RWLOCK_SUFFIX 1 +#define SDL_THREAD_WINDOWS 1 + +/* Enable RTC system */ +#define SDL_TIME_WINDOWS 1 /* Enable various timer systems */ -#define SDL_TIMER_WINDOWS 1 +#define SDL_TIMER_WINDOWS 1 /* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_DUMMY 1 -#define SDL_VIDEO_DRIVER_WINDOWS 1 - -#ifndef SDL_VIDEO_RENDER_D3D -#define SDL_VIDEO_RENDER_D3D 1 -#endif -#if !defined(SDL_VIDEO_RENDER_D3D11) && defined(HAVE_D3D11_H) -#define SDL_VIDEO_RENDER_D3D11 1 -#endif -#if !defined(SDL_VIDEO_RENDER_D3D12) && defined(HAVE_D3D12_H) -#define SDL_VIDEO_RENDER_D3D12 1 -#endif +#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_OFFSCREEN 1 +#define SDL_VIDEO_DRIVER_WINDOWS 1 +#define SDL_VIDEO_RENDER_D3D 1 +#ifdef HAVE_D3D11_H +#define SDL_VIDEO_RENDER_D3D11 1 +#endif +#define SDL_VIDEO_RENDER_D3D12 1 /* Enable OpenGL support */ -#ifndef SDL_VIDEO_OPENGL -#define SDL_VIDEO_OPENGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_WGL -#define SDL_VIDEO_OPENGL_WGL 1 -#endif -#ifndef SDL_VIDEO_RENDER_OGL -#define SDL_VIDEO_RENDER_OGL 1 -#endif -#ifndef SDL_VIDEO_RENDER_OGL_ES2 -#define SDL_VIDEO_RENDER_OGL_ES2 1 -#endif -#ifndef SDL_VIDEO_OPENGL_ES2 -#define SDL_VIDEO_OPENGL_ES2 1 -#endif -#ifndef SDL_VIDEO_OPENGL_EGL -#define SDL_VIDEO_OPENGL_EGL 1 -#endif +#define SDL_VIDEO_OPENGL 1 +#define SDL_VIDEO_OPENGL_WGL 1 +#define SDL_VIDEO_RENDER_OGL 1 +#define SDL_VIDEO_RENDER_OGL_ES2 1 +#define SDL_VIDEO_OPENGL_ES2 1 +#define SDL_VIDEO_OPENGL_EGL 1 /* Enable Vulkan support */ #define SDL_VIDEO_VULKAN 1 +#define SDL_VIDEO_RENDER_VULKAN 1 + +/* Enable GPU support */ +#ifdef HAVE_D3D11_H +#define SDL_GPU_D3D11 1 +#endif +#define SDL_GPU_D3D12 1 +#define SDL_GPU_VULKAN 1 +#define SDL_VIDEO_RENDER_GPU 1 /* Enable system power support */ #define SDL_POWER_WINDOWS 1 /* Enable filesystem support */ -#define SDL_FILESYSTEM_WINDOWS 1 +#define SDL_FILESYSTEM_WINDOWS 1 +#define SDL_FSOPS_WINDOWS 1 -#endif /* SDL_config_windows_h_ */ +/* Enable the camera driver */ +#define SDL_CAMERA_DRIVER_MEDIAFOUNDATION 1 +#define SDL_CAMERA_DRIVER_DUMMY 1 -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_build_config_windows_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_wingdk.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_wingdk.h similarity index 55% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_wingdk.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_wingdk.h index 2e329279db..502eb92994 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_wingdk.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_wingdk.h @@ -19,18 +19,15 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_wingdk_h_ -#define SDL_config_wingdk_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_wingdk_h_ +#define SDL_build_config_wingdk_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /* Windows GDK does not need Windows SDK version checks because it requires * a recent version of the Windows 10 SDK. */ -/* GDK only supports 64-bit */ -# define SIZEOF_VOIDP 8 - #ifdef __clang__ # define HAVE_GCC_ATOMICS 1 #endif @@ -40,45 +37,42 @@ #define HAVE_DSOUND_H 1 /* No SDK version checks needed for these because the SDK has to be new. */ #define HAVE_DXGI_H 1 +#define HAVE_DXGI1_6_H 1 #define HAVE_XINPUT_H 1 #define HAVE_WINDOWS_GAMING_INPUT_H 1 #define HAVE_D3D11_H 1 #define HAVE_ROAPI_H 1 -#define HAVE_D3D12_H 1 #define HAVE_SHELLSCALINGAPI_H 1 #define HAVE_MMDEVICEAPI_H 1 #define HAVE_AUDIOCLIENT_H 1 #define HAVE_TPCSHRD_H 1 #define HAVE_SENSORSAPI_H 1 +#define HAVE_GAMEINPUT_H 1 #if (defined(_M_IX86) || defined(_M_X64) || defined(_M_AMD64)) && (defined(_MSC_VER) && _MSC_VER >= 1600) -#define HAVE_IMMINTRIN_H 1 #elif defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 +# if !__has_include() +# define SDL_DISABLE_AVX 1 # endif +#else +# define SDL_DISABLE_AVX 1 #endif -/* This is disabled by default to avoid C runtime dependencies and manifest requirements */ -#ifdef HAVE_LIBC /* Useful headers */ -#define STDC_HEADERS 1 -#define HAVE_CTYPE_H 1 #define HAVE_FLOAT_H 1 #define HAVE_LIMITS_H 1 #define HAVE_MATH_H 1 #define HAVE_SIGNAL_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #define HAVE_STDINT_H 1 #define HAVE_STDIO_H 1 +#define HAVE_STDLIB_H 1 #define HAVE_STRING_H 1 +#define HAVE_WCHAR_H 1 /* C library functions */ +#define HAVE_LIBC 1 #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 #define HAVE_ABS 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 @@ -86,9 +80,6 @@ #define HAVE_MEMCMP 1 #define HAVE_STRLEN 1 #define HAVE__STRREV 1 -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__STRUPR */ -/* #undef HAVE__STRLWR */ #define HAVE_STRCHR 1 #define HAVE_STRRCHR 1 #define HAVE_STRSTR 1 @@ -103,45 +94,44 @@ #define HAVE_ATOF 1 #define HAVE_STRCMP 1 #define HAVE_STRNCMP 1 -#define HAVE__STRICMP 1 -#define HAVE__STRNICMP 1 -#define HAVE__WCSICMP 1 -#define HAVE__WCSNICMP 1 -#define HAVE__WCSDUP 1 -#define HAVE_ACOS 1 -#define HAVE_ASIN 1 -#define HAVE_ATAN 1 -#define HAVE_ATAN2 1 -#define HAVE_CEIL 1 -#define HAVE_COS 1 -#define HAVE_EXP 1 -#define HAVE_FABS 1 -#define HAVE_FLOOR 1 -#define HAVE_FMOD 1 -#define HAVE_LOG 1 -#define HAVE_LOG10 1 -#define HAVE_POW 1 -#define HAVE_SIN 1 -#define HAVE_SQRT 1 -#define HAVE_TAN 1 -#define HAVE_ACOSF 1 -#define HAVE_ASINF 1 -#define HAVE_ATANF 1 +#define HAVE_ACOS 1 +#define HAVE_ASIN 1 +#define HAVE_ATAN 1 +#define HAVE_ATAN2 1 +#define HAVE_CEIL 1 +#define HAVE_COS 1 +#define HAVE_EXP 1 +#define HAVE_FABS 1 +#define HAVE_FLOOR 1 +#define HAVE_FMOD 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 +#define HAVE_LOG 1 +#define HAVE_LOG10 1 +#define HAVE_POW 1 +#define HAVE_SIN 1 +#define HAVE_SQRT 1 +#define HAVE_TAN 1 +#define HAVE_ACOSF 1 +#define HAVE_ASINF 1 +#define HAVE_ATANF 1 #define HAVE_ATAN2F 1 -#define HAVE_CEILF 1 +#define HAVE_CEILF 1 #define HAVE__COPYSIGN 1 -#define HAVE_COSF 1 -#define HAVE_EXPF 1 -#define HAVE_FABSF 1 +#define HAVE_COSF 1 +#define HAVE_EXPF 1 +#define HAVE_FABSF 1 #define HAVE_FLOORF 1 -#define HAVE_FMODF 1 -#define HAVE_LOGF 1 +#define HAVE_FMODF 1 +#define HAVE_LOGF 1 #define HAVE_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#if defined(_MSC_VER) +#define HAVE_POWF 1 +#define HAVE_SINF 1 +#define HAVE_SQRTF 1 +#define HAVE_TANF 1 +#ifdef _MSC_VER /* These functions were added with the VC++ 2013 C runtime library */ #define HAVE_STRTOLL 1 #define HAVE_STRTOULL 1 @@ -152,102 +142,93 @@ #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 #define HAVE_SCALBNF 1 -#define HAVE_TRUNC 1 +#define HAVE_TRUNC 1 #define HAVE_TRUNCF 1 #define HAVE__FSEEKI64 1 -#ifdef _USE_MATH_DEFINES -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#define HAVE_STDINT_H 1 -#endif +#endif /* _MSC_VER */ /* Enable various audio drivers */ #if defined(HAVE_MMDEVICEAPI_H) && defined(HAVE_AUDIOCLIENT_H) #define SDL_AUDIO_DRIVER_WASAPI 1 #endif #define SDL_AUDIO_DRIVER_DSOUND 1 -#define SDL_AUDIO_DRIVER_WINMM 1 -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_DISK 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable various input drivers */ #define SDL_JOYSTICK_DINPUT 1 +#define SDL_JOYSTICK_GAMEINPUT 1 #define SDL_JOYSTICK_HIDAPI 1 -#define SDL_JOYSTICK_RAWINPUT 1 -#define SDL_JOYSTICK_VIRTUAL 1 -#ifdef HAVE_WINDOWS_GAMING_INPUT_H -#define SDL_JOYSTICK_WGI 1 -#endif +#define SDL_JOYSTICK_RAWINPUT 1 +#define SDL_JOYSTICK_VIRTUAL 1 +#define SDL_JOYSTICK_WGI 1 #define SDL_JOYSTICK_XINPUT 1 -#define SDL_HAPTIC_DINPUT 1 -#define SDL_HAPTIC_XINPUT 1 +#define SDL_HAPTIC_DINPUT 1 + +/* Enable various process implementations */ +#define SDL_PROCESS_WINDOWS 1 /* Enable the sensor driver */ #ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 +#define SDL_SENSOR_WINDOWS 1 #else -#define SDL_SENSOR_DUMMY 1 +#define SDL_SENSOR_DUMMY 1 #endif /* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 +#define SDL_LOADSO_WINDOWS 1 /* Enable various threading systems */ #define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 +#define SDL_THREAD_GENERIC_RWLOCK_SUFFIX 1 +#define SDL_THREAD_WINDOWS 1 + +/* Enable various time systems */ +#define SDL_TIME_WINDOWS 1 /* Enable various timer systems */ -#define SDL_TIMER_WINDOWS 1 +#define SDL_TIMER_WINDOWS 1 /* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_DUMMY 1 -#define SDL_VIDEO_DRIVER_WINDOWS 1 - -#ifndef SDL_VIDEO_RENDER_D3D -#define SDL_VIDEO_RENDER_D3D 1 -#endif -#if !defined(SDL_VIDEO_RENDER_D3D11) && defined(HAVE_D3D11_H) -#define SDL_VIDEO_RENDER_D3D11 1 -#endif -#if !defined(SDL_VIDEO_RENDER_D3D12) && defined(HAVE_D3D12_H) -#define SDL_VIDEO_RENDER_D3D12 1 +#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_WINDOWS 1 +#define SDL_VIDEO_RENDER_D3D 1 +#ifdef HAVE_D3D11_H +#define SDL_VIDEO_RENDER_D3D11 1 #endif +#define SDL_VIDEO_RENDER_D3D12 1 /* Enable OpenGL support */ -#ifndef SDL_VIDEO_OPENGL -#define SDL_VIDEO_OPENGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_WGL -#define SDL_VIDEO_OPENGL_WGL 1 -#endif -#ifndef SDL_VIDEO_RENDER_OGL -#define SDL_VIDEO_RENDER_OGL 1 -#endif -#ifndef SDL_VIDEO_RENDER_OGL_ES2 -#define SDL_VIDEO_RENDER_OGL_ES2 1 -#endif -#ifndef SDL_VIDEO_OPENGL_ES2 -#define SDL_VIDEO_OPENGL_ES2 1 -#endif -#ifndef SDL_VIDEO_OPENGL_EGL -#define SDL_VIDEO_OPENGL_EGL 1 -#endif +#define SDL_VIDEO_OPENGL 1 +#define SDL_VIDEO_OPENGL_WGL 1 +#define SDL_VIDEO_RENDER_OGL 1 +#define SDL_VIDEO_RENDER_OGL_ES2 1 +#define SDL_VIDEO_OPENGL_ES2 1 +#define SDL_VIDEO_OPENGL_EGL 1 /* Enable Vulkan support */ #define SDL_VIDEO_VULKAN 1 +#define SDL_VIDEO_RENDER_VULKAN 1 + +/* Enable GPU support */ +#ifdef HAVE_D3D11_H +#define SDL_GPU_D3D11 1 +#endif +#define SDL_GPU_D3D12 1 +#define SDL_GPU_VULKAN 1 +#define SDL_VIDEO_RENDER_GPU 1 /* Enable system power support */ #define SDL_POWER_WINDOWS 1 /* Enable filesystem support */ -#define SDL_FILESYSTEM_WINDOWS 1 +#define SDL_FILESYSTEM_WINDOWS 1 +#define SDL_FSOPS_WINDOWS 1 + +/* Enable the camera driver (src/camera/dummy/\*.c) */ /* !!! FIXME */ +#define SDL_CAMERA_DRIVER_DUMMY 1 -#endif /* SDL_config_wingdk_h_ */ +/* Use the (inferior) GDK text input method for GDK platforms */ +/*#define SDL_GDK_TEXTINPUT 1*/ -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_build_config_wingdk_h_ */ diff --git a/code/thirdparty/SDL2-2.32.8/include/SDL_config_xbox.h b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_xbox.h similarity index 57% rename from code/thirdparty/SDL2-2.32.8/include/SDL_config_xbox.h rename to code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_xbox.h index a06f52e544..5834e71f6f 100644 --- a/code/thirdparty/SDL2-2.32.8/include/SDL_config_xbox.h +++ b/code/thirdparty/SDL3-3.2.18/include/build_config/SDL_build_config_xbox.h @@ -19,18 +19,15 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDL_config_wingdk_h_ -#define SDL_config_wingdk_h_ -#define SDL_config_h_ +#ifndef SDL_build_config_wingdk_h_ +#define SDL_build_config_wingdk_h_ +#define SDL_build_config_h_ -#include "SDL_platform.h" +#include /* Windows GDK does not need Windows SDK version checks because it requires * a recent version of the Windows 10 SDK. */ -/* GDK only supports 64-bit */ -# define SIZEOF_VOIDP 8 - #ifdef __clang__ # define HAVE_GCC_ATOMICS 1 #endif @@ -42,53 +39,46 @@ /* #define HAVE_DXGI_H 1 */ #define HAVE_XINPUT_H 1 /*#define HAVE_WINDOWS_GAMING_INPUT_H 1*/ -/*#define HAVE_D3D11_H 1*/ /*#define HAVE_ROAPI_H 1*/ -#define HAVE_D3D12_H 1 /*#define HAVE_SHELLSCALINGAPI_H 1*/ #define HAVE_MMDEVICEAPI_H 1 #define HAVE_AUDIOCLIENT_H 1 /*#define HAVE_TPCSHRD_H 1*/ /*#define HAVE_SENSORSAPI_H 1*/ +#define HAVE_GAMEINPUT_H 1 #if (defined(_M_IX86) || defined(_M_X64) || defined(_M_AMD64)) && (defined(_MSC_VER) && _MSC_VER >= 1600) -#define HAVE_IMMINTRIN_H 1 #elif defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 +# if !__has_include() +# define SDL_DISABLE_AVX 1 # endif +#else +# define SDL_DISABLE_AVX 1 #endif -/* This is disabled by default to avoid C runtime dependencies and manifest requirements */ -#ifdef HAVE_LIBC /* Useful headers */ -#define STDC_HEADERS 1 -#define HAVE_CTYPE_H 1 #define HAVE_FLOAT_H 1 #define HAVE_LIMITS_H 1 #define HAVE_MATH_H 1 #define HAVE_SIGNAL_H 1 +#define HAVE_STDARG_H 1 +#define HAVE_STDDEF_H 1 #define HAVE_STDINT_H 1 #define HAVE_STDIO_H 1 +#define HAVE_STDLIB_H 1 #define HAVE_STRING_H 1 +#define HAVE_WCHAR_H 1 /* C library functions */ +#define HAVE_LIBC 1 #define HAVE_MALLOC 1 -#define HAVE_CALLOC 1 -#define HAVE_REALLOC 1 -#define HAVE_FREE 1 -#define HAVE_ALLOCA 1 -#define HAVE_QSORT 1 -#define HAVE_BSEARCH 1 #define HAVE_ABS 1 #define HAVE_MEMSET 1 #define HAVE_MEMCPY 1 #define HAVE_MEMMOVE 1 #define HAVE_MEMCMP 1 #define HAVE_STRLEN 1 +#define HAVE_STRPBRK 1 #define HAVE__STRREV 1 -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__STRUPR */ -/* #undef HAVE__STRLWR */ #define HAVE_STRCHR 1 #define HAVE_STRRCHR 1 #define HAVE_STRSTR 1 @@ -103,45 +93,44 @@ #define HAVE_ATOF 1 #define HAVE_STRCMP 1 #define HAVE_STRNCMP 1 -#define HAVE__STRICMP 1 -#define HAVE__STRNICMP 1 -#define HAVE__WCSICMP 1 -#define HAVE__WCSNICMP 1 -#define HAVE__WCSDUP 1 -#define HAVE_ACOS 1 -#define HAVE_ASIN 1 -#define HAVE_ATAN 1 -#define HAVE_ATAN2 1 -#define HAVE_CEIL 1 -#define HAVE_COS 1 -#define HAVE_EXP 1 -#define HAVE_FABS 1 -#define HAVE_FLOOR 1 -#define HAVE_FMOD 1 -#define HAVE_LOG 1 -#define HAVE_LOG10 1 -#define HAVE_POW 1 -#define HAVE_SIN 1 -#define HAVE_SQRT 1 -#define HAVE_TAN 1 -#define HAVE_ACOSF 1 -#define HAVE_ASINF 1 -#define HAVE_ATANF 1 +#define HAVE_ACOS 1 +#define HAVE_ASIN 1 +#define HAVE_ATAN 1 +#define HAVE_ATAN2 1 +#define HAVE_CEIL 1 +#define HAVE_COS 1 +#define HAVE_EXP 1 +#define HAVE_FABS 1 +#define HAVE_FLOOR 1 +#define HAVE_FMOD 1 +#define HAVE_ISINF 1 +#define HAVE_ISINF_FLOAT_MACRO 1 +#define HAVE_ISNAN 1 +#define HAVE_ISNAN_FLOAT_MACRO 1 +#define HAVE_LOG 1 +#define HAVE_LOG10 1 +#define HAVE_POW 1 +#define HAVE_SIN 1 +#define HAVE_SQRT 1 +#define HAVE_TAN 1 +#define HAVE_ACOSF 1 +#define HAVE_ASINF 1 +#define HAVE_ATANF 1 #define HAVE_ATAN2F 1 -#define HAVE_CEILF 1 +#define HAVE_CEILF 1 #define HAVE__COPYSIGN 1 -#define HAVE_COSF 1 -#define HAVE_EXPF 1 -#define HAVE_FABSF 1 +#define HAVE_COSF 1 +#define HAVE_EXPF 1 +#define HAVE_FABSF 1 #define HAVE_FLOORF 1 -#define HAVE_FMODF 1 -#define HAVE_LOGF 1 +#define HAVE_FMODF 1 +#define HAVE_LOGF 1 #define HAVE_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#if defined(_MSC_VER) +#define HAVE_POWF 1 +#define HAVE_SINF 1 +#define HAVE_SQRTF 1 +#define HAVE_TANF 1 +#ifdef _MSC_VER /* These functions were added with the VC++ 2013 C runtime library */ #define HAVE_STRTOLL 1 #define HAVE_STRTOULL 1 @@ -152,77 +141,64 @@ #define HAVE_ROUNDF 1 #define HAVE_SCALBN 1 #define HAVE_SCALBNF 1 -#define HAVE_TRUNC 1 +#define HAVE_TRUNC 1 #define HAVE_TRUNCF 1 #define HAVE__FSEEKI64 1 -#ifdef _USE_MATH_DEFINES -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#define HAVE_STDINT_H 1 -#endif +#endif /* _MSC_VER */ /* Enable various audio drivers */ #if defined(HAVE_MMDEVICEAPI_H) && defined(HAVE_AUDIOCLIENT_H) #define SDL_AUDIO_DRIVER_WASAPI 1 #endif /*#define SDL_AUDIO_DRIVER_DSOUND 1*/ -/*#define SDL_AUDIO_DRIVER_WINMM 1*/ -#define SDL_AUDIO_DRIVER_DISK 1 -#define SDL_AUDIO_DRIVER_DUMMY 1 +#define SDL_AUDIO_DRIVER_DISK 1 +#define SDL_AUDIO_DRIVER_DUMMY 1 /* Enable various input drivers */ -/*#define SDL_JOYSTICK_DINPUT 1*/ -/*#define SDL_JOYSTICK_HIDAPI 1*/ -/*#define SDL_JOYSTICK_RAWINPUT 1*/ -#define SDL_JOYSTICK_VIRTUAL 1 -#ifdef HAVE_WINDOWS_GAMING_INPUT_H -#define SDL_JOYSTICK_WGI 1 -#endif -#define SDL_JOYSTICK_XINPUT 1 -/*#define SDL_HAPTIC_DINPUT 1*/ -#define SDL_HAPTIC_XINPUT 1 +#define SDL_JOYSTICK_VIRTUAL 1 +/* This is XInputOnGameInput for GDK platforms: */ +/*#define SDL_JOYSTICK_XINPUT 1*/ +/* Native GameInput: */ +#define SDL_JOYSTICK_GAMEINPUT 1 +#define SDL_HAPTIC_DUMMY 1 + +/* Enable various process implementations */ +#define SDL_PROCESS_DUMMY 1 /* Enable the sensor driver */ #ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 +#define SDL_SENSOR_WINDOWS 1 #else -#define SDL_SENSOR_DUMMY 1 +#define SDL_SENSOR_DUMMY 1 #endif /* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 +#define SDL_LOADSO_WINDOWS 1 /* Enable various threading systems */ #define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 +#define SDL_THREAD_GENERIC_RWLOCK_SUFFIX 1 +#define SDL_THREAD_WINDOWS 1 + +/* Enable various time systems */ +#define SDL_TIME_WINDOWS 1 /* Enable various timer systems */ -#define SDL_TIMER_WINDOWS 1 +#define SDL_TIMER_WINDOWS 1 /* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_DUMMY 1 -#define SDL_VIDEO_DRIVER_WINDOWS 1 - -#if !defined(SDL_VIDEO_RENDER_D3D12) && defined(HAVE_D3D12_H) -#define SDL_VIDEO_RENDER_D3D12 1 -#endif +#define SDL_VIDEO_DRIVER_DUMMY 1 +#define SDL_VIDEO_DRIVER_WINDOWS 1 +#define SDL_VIDEO_RENDER_D3D12 1 /* Enable OpenGL support */ -#ifndef SDL_VIDEO_OPENGL -#define SDL_VIDEO_OPENGL 1 -#endif -#ifndef SDL_VIDEO_OPENGL_WGL -#define SDL_VIDEO_OPENGL_WGL 1 -#endif -#ifndef SDL_VIDEO_RENDER_OGL -#define SDL_VIDEO_RENDER_OGL 1 -#endif +#define SDL_VIDEO_OPENGL 1 +#define SDL_VIDEO_OPENGL_WGL 1 +#define SDL_VIDEO_RENDER_OGL 1 + +/* Enable GPU support */ +#define SDL_GPU_D3D12 1 +#define SDL_VIDEO_RENDER_GPU 1 /* Enable system power support */ /*#define SDL_POWER_WINDOWS 1*/ @@ -230,11 +206,18 @@ /* Enable filesystem support */ /* #define SDL_FILESYSTEM_WINDOWS 1*/ -#define SDL_FILESYSTEM_XBOX 1 +#define SDL_FSOPS_WINDOWS 1 + /* Disable IME as not supported yet (TODO: Xbox IME?) */ #define SDL_DISABLE_WINDOWS_IME 1 +/* Use the (inferior) GDK text input method for GDK platforms */ +#define SDL_GDK_TEXTINPUT 1 + +/* Enable the camera driver (src/camera/dummy/\*.c) */ +#define SDL_CAMERA_DRIVER_DUMMY 1 -#endif /* SDL_config_wingdk_h_ */ +/* Enable dialog subsystem */ +#define SDL_DIALOG_DUMMY 1 -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_build_config_wingdk_h_ */ diff --git a/code/thirdparty/libs/macos/libSDL3.dylib b/code/thirdparty/libs/macos/libSDL3.dylib new file mode 100755 index 0000000000..2cf258a6f4 Binary files /dev/null and b/code/thirdparty/libs/macos/libSDL3.dylib differ diff --git a/code/thirdparty/libs/win32/SDL2.dll b/code/thirdparty/libs/win32/SDL2.dll deleted file mode 100755 index fd0df339d2..0000000000 Binary files a/code/thirdparty/libs/win32/SDL2.dll and /dev/null differ diff --git a/code/thirdparty/libs/win32/SDL2.lib b/code/thirdparty/libs/win32/SDL2.lib deleted file mode 100644 index 3f684016b1..0000000000 Binary files a/code/thirdparty/libs/win32/SDL2.lib and /dev/null differ diff --git a/code/thirdparty/libs/win32/SDL2main.lib b/code/thirdparty/libs/win32/SDL2main.lib deleted file mode 100644 index 9f3856a93e..0000000000 Binary files a/code/thirdparty/libs/win32/SDL2main.lib and /dev/null differ diff --git a/code/thirdparty/libs/win32/SDL3.dll b/code/thirdparty/libs/win32/SDL3.dll new file mode 100644 index 0000000000..7cd66b0836 Binary files /dev/null and b/code/thirdparty/libs/win32/SDL3.dll differ diff --git a/code/thirdparty/libs/win32/SDL3.lib b/code/thirdparty/libs/win32/SDL3.lib new file mode 100644 index 0000000000..8bb49387ba Binary files /dev/null and b/code/thirdparty/libs/win32/SDL3.lib differ diff --git a/code/thirdparty/libs/win32/libSDL3.dll.a b/code/thirdparty/libs/win32/libSDL3.dll.a new file mode 100644 index 0000000000..cc27acbe35 Binary files /dev/null and b/code/thirdparty/libs/win32/libSDL3.dll.a differ diff --git a/code/thirdparty/libs/win64/SDL2.dll b/code/thirdparty/libs/win64/SDL2.dll deleted file mode 100644 index 7e378b954b..0000000000 Binary files a/code/thirdparty/libs/win64/SDL2.dll and /dev/null differ diff --git a/code/thirdparty/libs/win64/SDL2.lib b/code/thirdparty/libs/win64/SDL2.lib deleted file mode 100644 index 8006e2fd29..0000000000 Binary files a/code/thirdparty/libs/win64/SDL2.lib and /dev/null differ diff --git a/code/thirdparty/libs/win64/SDL2main.lib b/code/thirdparty/libs/win64/SDL2main.lib deleted file mode 100644 index 1543ae20c0..0000000000 Binary files a/code/thirdparty/libs/win64/SDL2main.lib and /dev/null differ diff --git a/code/thirdparty/libs/win64/SDL3.dll b/code/thirdparty/libs/win64/SDL3.dll new file mode 100644 index 0000000000..35d13f50cb Binary files /dev/null and b/code/thirdparty/libs/win64/SDL3.dll differ diff --git a/code/thirdparty/libs/win64/SDL3.lib b/code/thirdparty/libs/win64/SDL3.lib new file mode 100644 index 0000000000..f45f6324dc Binary files /dev/null and b/code/thirdparty/libs/win64/SDL3.lib differ diff --git a/code/thirdparty/libs/win64/libSDL3.dll.a b/code/thirdparty/libs/win64/libSDL3.dll.a new file mode 100644 index 0000000000..9f713aff71 Binary files /dev/null and b/code/thirdparty/libs/win64/libSDL3.dll.a differ diff --git a/misc/build-macos-sdl.sh b/misc/build-macos-sdl.sh index 2f68e5687c..3e668e8d63 100755 --- a/misc/build-macos-sdl.sh +++ b/misc/build-macos-sdl.sh @@ -13,13 +13,13 @@ set -e TMPDIR=$(mktemp -d) cd "$TMPDIR" -SDL_TARBALL="SDL2-${SDL_VERSION}.tar.gz" +SDL_TARBALL="SDL3-${SDL_VERSION}.tar.gz" SDL_URL="https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/${SDL_TARBALL}" -curl -sL "$SDL_URL" +curl -sLO "$SDL_URL" tar -xzf "$SDL_TARBALL" -SDL_DIR="SDL2-${SDL_VERSION}" +SDL_DIR="SDL3-${SDL_VERSION}" cd $TMPDIR/$SDL_DIR BUILD_DIR="build" @@ -29,9 +29,8 @@ cmake --build ${BUILD_DIR} --parallel $(sysctl -n hw.ncpu) DEST_DIR="${ROOT_DIR}/code/thirdparty/libs/macos/" mkdir -p ${DEST_DIR} -cp ${BUILD_DIR}/libSDL2-2.0.0.dylib ${DEST_DIR} -cp ${BUILD_DIR}/libSDL2main.a ${DEST_DIR} -install_name_tool -id @executable_path/libSDL2-2.0.0.dylib ${DEST_DIR}/libSDL2-2.0.0.dylib +cp ${BUILD_DIR}/libSDL3.dylib ${DEST_DIR} +install_name_tool -id @executable_path/libSDL3.dylib ${DEST_DIR}/libSDL3.dylib cd rm -rf "$TMPDIR" diff --git a/misc/lib-versions.sh b/misc/lib-versions.sh index 40e9d65689..1d901ca062 100644 --- a/misc/lib-versions.sh +++ b/misc/lib-versions.sh @@ -1,4 +1,4 @@ -SDL_VERSION=2.32.8 +SDL_VERSION=3.2.18 OGG_VERSION=1.3.6 VORBIS_VERSION=1.3.7 OPUS_VERSION=1.5.2 diff --git a/misc/update-libs.sh b/misc/update-libs.sh index 6519bfa2f5..a349c7edc2 100755 --- a/misc/update-libs.sh +++ b/misc/update-libs.sh @@ -76,28 +76,24 @@ prepare "https://github.com/kcat/openal-soft/archive/refs/tags/${OPENAL_VERSION} "" \ "\./include/AL/.*\.h" -prepare "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL2-${SDL_VERSION}.tar.gz" \ +prepare "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL3-${SDL_VERSION}.tar.gz" \ "" \ "\./include/.*\.h" TMPDIR=$(mktemp -d) cd ${TMPDIR} -curl -sL "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL2-devel-${SDL_VERSION}-mingw.tar.gz" | tar -xvz -curl -sL "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL2-devel-${SDL_VERSION}-VC.zip" \ - -o temp.zip && unzip -o temp.zip && rm temp.zip - -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x86/SDL2.dll ${CODE}/libs/win32/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x86/SDL2.lib ${CODE}/libs/win32/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x86/SDL2main.lib ${CODE}/libs/win32/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/i686-w64-mingw32/lib/libSDL2.dll.a ${CODE}/libs/win32/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/i686-w64-mingw32/lib/libSDL2main.a ${CODE}/libs/win32/ - -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x64/SDL2.dll ${CODE}/libs/win64/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x64/SDL2.lib ${CODE}/libs/win64/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/lib/x64/SDL2main.lib ${CODE}/libs/win64/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/x86_64-w64-mingw32/lib/libSDL2.dll.a ${CODE}/libs/win64/ -cp ${TMPDIR}/SDL2-${SDL_VERSION}/x86_64-w64-mingw32/lib/libSDL2main.a ${CODE}/libs/win64/ +curl -sL "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL3-devel-${SDL_VERSION}-mingw.tar.gz" | tar -xvz +curl -sL "https://github.com/libsdl-org/SDL/releases/download/release-${SDL_VERSION}/SDL3-devel-${SDL_VERSION}-VC.zip" \ + -o temp.zip && unzip -o temp.zip && rm temp.zip + +cp ${TMPDIR}/SDL3-${SDL_VERSION}/lib/x86/SDL3.dll ${CODE}/libs/win32/ +cp ${TMPDIR}/SDL3-${SDL_VERSION}/lib/x86/SDL3.lib ${CODE}/libs/win32/ +cp ${TMPDIR}/SDL3-${SDL_VERSION}/i686-w64-mingw32/lib/libSDL3.dll.a ${CODE}/libs/win32/ + +cp ${TMPDIR}/SDL3-${SDL_VERSION}/lib/x64/SDL3.dll ${CODE}/libs/win64/ +cp ${TMPDIR}/SDL3-${SDL_VERSION}/lib/x64/SDL3.lib ${CODE}/libs/win64/ +cp ${TMPDIR}/SDL3-${SDL_VERSION}/x86_64-w64-mingw32/lib/libSDL3.dll.a ${CODE}/libs/win64/ cd rm -r ${TMPDIR}