diff --git a/Makefile b/Makefile index 1a00eb9..caf6bd9 100644 --- a/Makefile +++ b/Makefile @@ -1,66 +1,80 @@ -ifeq ($(OS),Windows_NT) - DETECTED_OS := windows -else - UNAME_S := $(shell uname -s) +UNAME_M := $(shell uname -m) - ifeq ($(UNAME_S),Darwin) - DETECTED_OS := macos - else ifeq ($(UNAME_S),Linux) - DETECTED_OS := linux - else - DETECTED_OS := unknown - endif +ifeq ($(UNAME_M),x86_64) + ARCH := ARCHITECTURE_X64 +else ifneq ($(filter $(UNAME_M),i686,i386),) + ARCH := ARCHITECTURE_X86 +else ifneq ($(filter $(UNAME_M),aarch64 arm64),) + ARCH := ARCHITECTURE_ARM64 +else ifneq ($(filter $(UNAME_M),armv7l armv6l),) + ARCH := ARCHITECTURE_ARM32 +endif + +UNAME_S := $(shell uname -s) + +ifeq ($(UNAME_S),Darwin) + OS := OS_MACOS +else ifeq ($(UNAME_S),Linux) + OS := OS_LINUX endif CC = clang -UFLAGS = -FLAGS = -ansi -pedantic -pedantic-errors -Wno-long-long -Wall -Wextra \ - -Wincompatible-pointer-types \ - -Wint-conversion -Wimplicit-int-float-conversion -Wformat \ - -Wno-strict-prototypes -Wno-missing-field-initializers \ - -Wno-unused-function -Wno-unused-parameter -Wno-unused-variable \ - -Wno-unused-but-set-variable \ - -fno-caret-diagnostics -fno-show-column +ifeq ($(CC),clang) + COMP := COMPILER_CLANG +else ifeq ($(CC),gcc) + COMP := COMPILER_GCC +endif -ifeq ($(DETECTED_OS),macos) - UFLAGS = -glldb - INCLUDE = -I./sdl/include/ - LIBS = ./sdl/lib/arm-macos/libSDL2.a -lm +# -ansi -pedantic -pedantic-errors +CFLAGS = -Wno-long-long -Wall -Wextra \ + -Wincompatible-pointer-types \ + -Wint-conversion -Wimplicit-int-float-conversion -Wformat \ + -Wno-strict-prototypes -Wno-missing-field-initializers \ + -Wno-unused-function -Wno-unused-parameter -Wno-unused-variable \ + -Wno-unused-but-set-variable \ + -fno-caret-diagnostics -fno-show-column + +ifeq ($(OS),OS_MACOS) + FLAGS = -glldb + INCLUDE = -I./libs/include/ + LIBS = ./libs/lib/arm-macos/libSDL3.a -lm FRAMEWORKS = -framework Cocoa -framework IOKit -framework CoreAudio \ -framework AudioToolbox -framework ForceFeedback \ -framework Carbon -framework GameController \ -framework Metal -framework QuartzCore \ -framework CoreHaptics -else ifeq ($(DETECTED_OS),linux) - UFLAGS = -ggdb -D_POSIX_C_SOURCE=200809L - INCLUDE = -I./sdl/include/ - LIBS = ./sdl/lib/x86_64-linux/libSDL2.a -lm -lX11 - FRAMEWORKS = -else - INCLUDE = - LIBS = +else ifeq ($(OS),OS_LINUX) + FLAGS = -ggdb -D_POSIX_C_SOURCE=200809L -no-pie + INCLUDE = -I./libs/include/ + LIBS = ./libs/lib/x86_64-linux/libSDL3.a -lm -lX11 FRAMEWORKS = endif EXE=handmadehero -default: tags libhandmade $(EXE) +default: libhandmade $(EXE) libhandmade: handmade.c - @ $(CC) $(FLAGS) $(UFLAGS) -fPIC -shared $(INCLUDE) $^ $(LIBS) \ + $(CC) $(CFLAGS) $(FLAGS) \ + -D$(ARCH)=1 -D$(OS)=1 -D$(COMP)=1 \ + -fPIC -shared $(INCLUDE) $^ $(LIBS) \ $(FRAMEWORKS) -o libhandmade.so $(EXE): sdl_handmade.c libhandmade - @ $(CC) $(FLAGS) $(UFLAGS) $(INCLUDE) sdl_handmade.c $(LIBS) \ - $(FRAMEWORKS) -o $@ $(ifneq $(filter $(DETECTED_OS), macos linux), \ + $(CC) $(CFLAGS) $(FLAGS) \ + -D$(ARCH)=1 -D$(OS)=1 -D$(COMP)=1 \ + $(INCLUDE) $< $(LIBS) \ + $(FRAMEWORKS) -o $@ $(ifneq $(filter $(OS), OS_MACOS OS_LINUX), \ /link /FORCE:MULTIPLE) +watch: + @ while true; do \ + inotifywait -q -q -e 'modify' . && clear && make -B; \ + done + run: @ ./$(EXE) -tags: $(OBJS) - @ ctags -R *.h *.c - clean: - @rm -rf $(EXE) $(EXE).dSYM libhandmade.so libhandmade.so.dSYM tags + @ rm -rf $(EXE) $(EXE).dSYM libhandmade.so libhandmade.so.dSYM diff --git a/build_linux.sh b/build_linux.sh deleted file mode 100644 index 2a864a9..0000000 --- a/build_linux.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/sh - -CC = clang - diff --git a/config.h b/config.h new file mode 100644 index 0000000..5fe3900 --- /dev/null +++ b/config.h @@ -0,0 +1,14 @@ +#ifndef CONFIG_SENTRY +#define CONFIG_SENTRY + +/* TODO: How does ... handle this in his projects? */ + +#ifndef BUILD_DEBUG +#define BUILD_DEBUG 1 +#endif + +#ifndef BUILD_INTERNAL +#define BUILD_INTERNAL 1 +#endif + +#endif diff --git a/core.h b/core.h deleted file mode 100644 index 2fb0eb6..0000000 --- a/core.h +++ /dev/null @@ -1,130 +0,0 @@ -#ifndef CORE_H -#define CORE_H - -/* ---- Switches ------------------------------------------------------- */ - -#ifndef BUILD_DEBUG -#define BUILD_DEBUG 1 -#endif - -#ifndef BUILD_INTERNAL -#define BUILD_INTERNAL 1 -#endif - -/* ---- Environment Detection ------------------------------------------ */ - -/* Architecture */ - -#ifndef ARCHITECTURE_X64 -#define ARCHITECTURE_X64 1 -#endif - -#ifndef ARCHITECTURE_X86 -#define ARCHITECTURE_X86 0 -#endif - -#ifndef ARCHITECTURE_ARM64 -#define ARCHITECTURE_ARM64 0 -#endif - -#ifndef ARCHITECTURE_ARM32 -#define ARCHITECTURE_ARM32 0 -#endif - -/* OS */ - -#ifndef OS_LINUX -#define OS_LINUX 1 -#endif - -#ifndef OS_WINDOWS -#define OS_WINDOWS 0 -#endif - -#ifndef OS_MACOS -#define OS_MACOS 0 -#endif - -/* Compiler */ - -#ifndef COMPILER_CLANG -#define COMPILER_CLANG 1 -#endif - -#ifndef COMPILER_MSVC -#define COMPILER_MSVC 0 -#endif - -#ifndef COMPILER_GCC -#define COMPILER_GCC 0 -#endif - -/* ---- Units ---------------------------------------------------------- */ - -#define KB(n) (((unsigned long long)(n)) << 10) -#define MB(n) (((unsigned long long)(n)) << 20) -#define GB(n) (((unsigned long long)(n)) << 30) -#define TB(n) (((unsigned long long)(n)) << 40) - -/* ---- Clamps, Min/Max ------------------------------------------------ */ - -#define MIN(A,B) (((A) < (B)) ? (A) : (B)) -#define MAX(A,B) (((A) > (B)) ? (A) : (B)) -#define CLAMP_TOP(A, X) Min(A, X) -#define CLAMP_BOT(X, B) Max(X, B) -#define CLAMP(A, X, B) (((X) < (A)) ? (A) : ((X) > (B)) ? (B) : (X)) - -/* ---- Asserts -------------------------------------------------------- */ - -#if COMPILER_CLANG || COMPILER_GCC -#define TRAP() __builtin_trap() -#elif COMPILER_MSVC -#define TRAP() __debugbreak() -#else -#error Unknow debug break for the compiler . . . -#endif - -#define ASSERT_ALWAYS(x) do { if(!(x)) { TRAP(); } } while(0) -#if BUILD_DEBUG -#define ASSERT(x) ASSERT_ALWAYS(x) -#else -#define ASSERT(x) (void)(x) -#endif - -/* ---- Helper Macros -------------------------------------------------- */ - -#define STRINGIFY_(S) #S -#define STRINGIFY(S) STRINGIFY_(S) - -#define GLUE_(A, B) A##B -#define GLUE(A, B) GLUE_(A,B) - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0])) - -#define SWAP(T, a, b) do { T t__ = a; a = b; b = t__; } while(0) - -/* ---- Constants ------------------------------------------------------ */ - -#define PI 3.14159265358979323846 - -#define MAX_U64 (U64)0xffffffffffffffff -#define MAX_U32 (U32)0xffffffff -#define MAX_U16 (U16)0xffff -#define MAX_U8 (U8)0xff - -#define MIN_U64 (U64)0x0 -#define MIN_U32 (U32)0x0 -#define MIN_U16 (U16)0x0 -#define MIN_U8 (U8)0x0 - -#define MAX_S64 (S64)0x7fffffffffffffff -#define MAX_S32 (S32)0x7fffffff -#define MAX_S16 (S16)0x7fff -#define MAX_S8 (S8)0x7f - -#define MIN_S64 (S64)0x8000000000000000 -#define MIN_S32 (S32)0x80000000 -#define MIN_S16 (S16)0x8000 -#define MIN_S8 (S8)0x80 - -#endif diff --git a/handmade.c b/handmade.c index 204138e..888732a 100644 --- a/handmade.c +++ b/handmade.c @@ -1,4 +1,3 @@ -#include "core.h" #include "handmade.h" #include "handmade_math.h" #include "sdl_handmade.h" @@ -9,429 +8,434 @@ #include "handmade_tile.c" #include +#include /* malloc */ #include /* memset */ +#include -static void GameOutputSound(struct game_state *GameState, - struct game_sound_output_buffer *SoundBuffer, - int ToneHz) +static void game_output_sound(struct game_state *game_state, + struct game_sound_output_buffer *sound_buffer, + int tone_hz) { /* - short ToneVolume, *SampleOut; - int WavePeriod, SampleIndex; + short tone_volume, *sample_out; + int wave_period, sample_index; - ToneVolume = 0; - WavePeriod = SoundBuffer->SamplesPerSecond / ToneHz; + tone_volume = 0; + wave_period = sound_buffer->SamplesPerSecond / tone_hz; - SampleOut = SoundBuffer->Samples; + sample_out = sound_buffer->Samples; - for(SampleIndex = 0; - SampleIndex < SoundBuffer->SampleCount; - SampleIndex++) + for(sample_index = 0; + sample_index < sound_buffer->SampleCount; + sample_index++) { float SineValue; short SampleValue; - SineValue = sinf(GameState->tSine); - SampleValue = (short)(SineValue * ToneVolume); - *SampleOut++ = SampleValue; - *SampleOut++ = SampleValue; + SineValue = sinf(game_state->tSine); + SampleValue = (short)(SineValue * tone_volume); + *sample_out++ = SampleValue; + *sample_out++ = SampleValue; - GameState->tSine += 2.0f * (float)PI * 1.0f / (float)WavePeriod; - if(GameState->tSine > 2.0f*(float)PI) { - GameState->tSine -= 2.0f*(float)PI; + game_state->tSine += 2.0f * (float)PI * 1.0f / (float)wave_period; + if(game_state->tSine > 2.0f*(float)PI) { + game_state->tSine -= 2.0f*(float)PI; } } */ } -static void ClearBackground(struct game_offscreen_buffer *Buffer) +static void clear_background(struct game_offscreen_buffer *buffer) { - int Width = Buffer->Width; - int Height = Buffer->Height; + int width = buffer->width; + int height = buffer->height; - int X; - for(X = 0; X < Width * Height; X++) { - unsigned int *Pixel = &((unsigned int *)Buffer->Memory)[X]; - *Pixel = 0xFFFFFF; + int x; + for(x = 0; x < width * height; x++) { + unsigned int *pixel = &((unsigned int *)buffer->memory)[x]; + *pixel = 0xFFFFFF; } } -static void DrawRectangle(struct game_offscreen_buffer *Buffer, - struct v2 vMin, struct v2 vMax, - float R, float G, float B) +static void draw_rectangle(struct game_offscreen_buffer *buffer, + struct v2 v_min, struct v2 v_max, + float r, float g, float b) { - int Y, X; + int y, x; - int Width, Height; + int width, height; - int MinX, MinY, MaxX, MaxY; + int min_x, min_y, max_x, max_y; - unsigned int Color; + unsigned int color; - unsigned char *Row; - unsigned int *Pixel; + unsigned char *row; + unsigned int *pixel; - MinX = RoundFloatToInt(vMin.X); - MinY = RoundFloatToInt(vMin.Y); - MaxX = RoundFloatToInt(vMax.X); - MaxY = RoundFloatToInt(vMax.Y); + min_x = round_float_to_int(v_min.x); + min_y = round_float_to_int(v_min.y); + max_x = round_float_to_int(v_max.x); + max_y = round_float_to_int(v_max.y); - Width = Buffer->Width; - Height = Buffer->Height; + width = buffer->width; + height = buffer->height; - if(MinX < 0) - MinX = 0; - if(MinY < 0) - MinY = 0; + if(min_x < 0) + min_x = 0; + if(min_y < 0) + min_y = 0; - if(MaxX > Width) - MaxX = Width; - if(MaxY > Height) - MaxY = Height; + if(max_x > width) + max_x = width; + if(max_y > height) + max_y = height; - /*unsigned int Color = (unsigned int)((RoundFloatToInt(R * 255.0f) << 16) | - (RoundFloatToInt(G * 255.0f) << 8) | - (RoundFloatToInt(B * 255.0f) << 0));*/ - Color = (unsigned int)((RoundFloatToInt(255.0f) << 24) | - (RoundFloatToInt(R * 255.0f) << 16) | - (RoundFloatToInt(G * 255.0f) << 8) | - (RoundFloatToInt(B * 255.0f) << 0)); + /*unsigned int color = (unsigned int)((round_float_to_int(r * 255.0f) << 16) | + (round_float_to_int(g * 255.0f) << 8) | + (round_float_to_int(b * 255.0f) << 0));*/ + color = (unsigned int)((round_float_to_int(255.0f) << 24) | + (round_float_to_int(r * 255.0f) << 16) | + (round_float_to_int(g * 255.0f) << 8) | + (round_float_to_int(b * 255.0f) << 0)); - Row = ((unsigned char *)Buffer->Memory + MinX*Buffer->BytesPerPixel + - MinY*Buffer->Pitch); - for(Y = MinY; Y < MaxY; Y++) { - Pixel = (unsigned int *)Row; - for(X = MinX; X < MaxX; X++) { - *(unsigned int *)Pixel = Color; - Pixel++; + row = ((unsigned char *)buffer->memory + min_x*buffer->bytes_per_pixel + + min_y*buffer->pitch); + for(y = min_y; y < max_y; y++) { + pixel = (unsigned int *)row; + for(x = min_x; x < max_x; x++) { + *(unsigned int *)pixel = color; + pixel++; } - Row += Buffer->Pitch; + row += buffer->pitch; } } -static void DrawBitmap(struct game_offscreen_buffer *Buffer, - struct loaded_bitmap *Bitmap, - float RelX, float RelY, int AlignX, int AlignY) +static void draw_bitmap(struct game_offscreen_buffer *buffer, + struct loaded_bitmap *bitmap, + float rel_x, float rel_y, int align_x, int align_y) { - int MinX, MinY, MaxX, MaxY; + int min_x, min_y, max_x, max_y; - int Width, Height; + int width, height; - int SourceOffsetX, SourceOffsetY; + int source_offset_x, source_offset_y; - unsigned int *SourceRow; - unsigned char *DestRow; + unsigned int *source_row; + unsigned char *dest_row; - int Y, X; + int y, x; - RelX -= (float)AlignX; - RelY -= (float)AlignY; + rel_x -= (float)align_x; + rel_y -= (float)align_y; - MinX = RoundFloatToInt(RelX); - MinY = RoundFloatToInt(RelY); - MaxX = RoundFloatToInt(RelX + (float)Bitmap->Width); - MaxY = RoundFloatToInt(RelY + (float)Bitmap->Height); + min_x = round_float_to_int(rel_x); + min_y = round_float_to_int(rel_y); + max_x = round_float_to_int(rel_x + (float)bitmap->width); + max_y = round_float_to_int(rel_y + (float)bitmap->height); - Width = Buffer->Width; - Height = Buffer->Height; + width = buffer->width; + height = buffer->height; - SourceOffsetX = 0; - if(MinX < 0) { - SourceOffsetX = -MinX; - MinX = 0; + source_offset_x = 0; + if(min_x < 0) { + source_offset_x = -min_x; + min_x = 0; } - SourceOffsetY = 0; - if(MinY < 0) { - SourceOffsetY = -MinY; - MinY = 0; + source_offset_y = 0; + if(min_y < 0) { + source_offset_y = -min_y; + min_y = 0; } - if(MaxX > Width) - MaxX = Width; - if(MaxY > Height) - MaxY = Height; + if(max_x > width) + max_x = width; + if(max_y > height) + max_y = height; - SourceRow = - Bitmap->Pixels + Bitmap->Width*(Bitmap->Height - 1); - SourceRow += -Bitmap->Width*SourceOffsetY + SourceOffsetX; - DestRow = ((unsigned char *)Buffer->Memory + - MinX*Buffer->BytesPerPixel + MinY*Buffer->Pitch); - for(Y = MinY; Y < MaxY; Y++) { - unsigned int *Dest = (unsigned int *)DestRow; - unsigned int *Source = SourceRow; - for(X = MinX; X < MaxX; X++) { - float SA = (float)((*Source >> 24) & 0xFF); - float SR = (float)((*Source >> 16) & 0xFF); - float SG = (float)((*Source >> 8) & 0xFF); - float SB = (float)((*Source >> 0) & 0xFF); + source_row = + bitmap->pixels + bitmap->width*(bitmap->height - 1); + source_row += -bitmap->width*source_offset_y + source_offset_x; + dest_row = ((unsigned char *)buffer->memory + + min_x*buffer->bytes_per_pixel + min_y*buffer->pitch); + for(y = min_y; y < max_y; y++) { + unsigned int *dest = (unsigned int *)dest_row; + unsigned int *source = source_row; + for(x = min_x; x < max_x; x++) { + float sa = (float)((*source >> 24) & 0xFF); + float sr = (float)((*source >> 16) & 0xFF); + float sg = (float)((*source >> 8) & 0xFF); + float sb = (float)((*source >> 0) & 0xFF); - float DR = (float)((*Dest >> 16) & 0xFF); - float DG = (float)((*Dest >> 8) & 0xFF); - float DB = (float)((*Dest >> 0) & 0xFF); + float da = (float)((*dest >> 24) & 0xFF); + float dr = (float)((*dest >> 16) & 0xFF); + float dg = (float)((*dest >> 8) & 0xFF); + float db = (float)((*dest >> 0) & 0xFF); - float A = SA / 255.0f; + float ar = sa / 255.0f; /* TODO: This should be replaced by premultiplied alpha. */ - float R = (1.0f-A)*DR + A*SR; - float G = (1.0f-A)*DG + A*SG; - float B = (1.0f-A)*DB + A*SB; + float a = (1.0f-ar)*da + ar*sa; + float r = (1.0f-ar)*dr + ar*sr; + float g = (1.0f-ar)*dg + ar*sg; + float b = (1.0f-ar)*db + ar*sb; - *Dest = (((unsigned int)RoundFloatToInt(SA) << 24) | - ((unsigned int)RoundFloatToInt(R) << 16) | - ((unsigned int)RoundFloatToInt(G) << 8) | - ((unsigned int)RoundFloatToInt(B) << 0)); + *dest = (((unsigned int)round_float_to_int(a) << 24) | + ((unsigned int)round_float_to_int(r) << 16) | + ((unsigned int)round_float_to_int(g) << 8) | + ((unsigned int)round_float_to_int(b) << 0)); - Dest++; - Source++; + dest++; + source++; } - DestRow += Buffer->Pitch; - SourceRow -= Bitmap->Width; + dest_row += buffer->pitch; + source_row -= bitmap->width; } } #pragma pack(push, 1) struct bitmap_header { - unsigned short FileType; - unsigned int FileSize; - unsigned short Reserved1; - unsigned short Reserved2; - unsigned int BitmapOffset; - unsigned int Size; - int Width; - int Height; - unsigned short Planes; - unsigned short BitsPerPixel; - unsigned int Compression; - unsigned int SizeOfBitmap; - int HorzResolution; - int VertResolution; - unsigned int ColorsUsed; - unsigned int ColorsImportant; + unsigned short file_type; + unsigned int file_size; + unsigned short reserved1; + unsigned short reserved2; + unsigned int bitmap_offset; + unsigned int size; + int width; + int height; + unsigned short planes; + unsigned short bits_per_pixel; + unsigned int compression; + unsigned int size_of_bitmap; + int horz_resolution; + int vert_resolution; + unsigned int colors_used; + unsigned int colors_important; - unsigned int RedMask; - unsigned int GreenMask; - unsigned int BlueMask; + unsigned int red_mask; + unsigned int green_mask; + unsigned int blue_mask; }; #pragma pack(pop) -static struct loaded_bitmap DEBUGLoadBMP(struct thread_context *Thread, +static struct loaded_bitmap debug_load_bmp(struct thread_context *thread, struct debug_read_file_result - (*DEBUGPlatformReadEntireFile)(struct thread_context *Thread, - const char *), char *FileName) + (*debug_platform_read_entire_file)(struct thread_context *thread, + const char *), char *file_name) { - struct loaded_bitmap Result; + struct loaded_bitmap result; - struct debug_read_file_result ReadResult; + struct debug_read_file_result read_result; - memset(&Result, 0, sizeof(Result)); + memset(&result, 0, sizeof(result)); - ReadResult = DEBUGPlatformReadEntireFile(Thread, FileName); - if(ReadResult.ContentsSize > 0) { - struct bitmap_header *Header; + read_result = debug_platform_read_entire_file(thread, file_name); + if(read_result.contents_size > 0) { + struct bitmap_header *header; - unsigned int *Pixels; + unsigned int *pixels; - unsigned int RedMask, GreenMask, BlueMask, AlphaMask; + unsigned int red_mask, green_mask, blue_mask, alpha_mask; - struct bit_scan_result RedShift, GreenShift, - BlueShift, AlphaShift; + struct bit_scan_result red_shift, green_shift, + blue_shift, alpha_shift; - unsigned int *SourceDest; + unsigned int *source_dest; - int X, Y; + int x, y; - Header = (struct bitmap_header *)ReadResult.Contents; + header = (struct bitmap_header *)read_result.contents; - Pixels = (unsigned int *)((unsigned char *)ReadResult.Contents + - Header->BitmapOffset); - Result.Pixels = Pixels; - Result.Width = Header->Width; - Result.Height = Header->Height; + pixels = (unsigned int *)((unsigned char *)read_result.contents + + header->bitmap_offset); + result.pixels = pixels; + result.width = header->width; + result.height = header->height; - ASSERT(Header->Compression == 3); + assert(header->compression == 3); - /* NOTE: The byte order in memory is determined by the Header. */ + /* NOTE: The byte order in memory is determined by the header. */ - RedMask = Header->RedMask; - GreenMask = Header->GreenMask; - BlueMask = Header->BlueMask; - AlphaMask = ~(RedMask | GreenMask | BlueMask); + red_mask = header->red_mask; + green_mask = header->green_mask; + blue_mask = header->blue_mask; + alpha_mask = ~(red_mask | green_mask | blue_mask); - RedShift = FindLeastSignificantSetBit(RedMask); - GreenShift = FindLeastSignificantSetBit(GreenMask); - BlueShift = FindLeastSignificantSetBit(BlueMask); - AlphaShift = FindLeastSignificantSetBit(AlphaMask); + red_shift = find_least_significant_set_bit(red_mask); + green_shift = find_least_significant_set_bit(green_mask); + blue_shift = find_least_significant_set_bit(blue_mask); + alpha_shift = find_least_significant_set_bit(alpha_mask); - ASSERT(RedShift.Found); - ASSERT(GreenShift.Found); - ASSERT(BlueShift.Found); - ASSERT(AlphaShift.Found); + assert(red_shift.found); + assert(green_shift.found); + assert(blue_shift.found); + assert(alpha_shift.found); - SourceDest = Pixels; - for(Y = 0; Y < Header->Height; Y++) { - for(X = 0; X < Header->Width; X++) { - unsigned int C = *SourceDest; + source_dest = pixels; + for(y = 0; y < header->height; y++) { + for(x = 0; x < header->width; x++) { + unsigned int c = *source_dest; - *SourceDest = ((((C >> AlphaShift.Index) & 0xFF) << 24) | - (((C >> RedShift.Index ) & 0xFF) << 16) | - (((C >> GreenShift.Index) & 0xFF) << 8) | - (((C >> BlueShift.Index ) & 0xFF) << 0)); - SourceDest++; + *source_dest = ((((c >> alpha_shift.index) & 0xFF) << 24) | + (((c >> red_shift.index ) & 0xFF) << 16) | + (((c >> green_shift.index) & 0xFF) << 8) | + (((c >> blue_shift.index ) & 0xFF) << 0)); + source_dest++; } } } - return Result; + return result; } -static struct entity *GetEntity(struct game_state *GameState, - unsigned int Index) +static struct entity *get_entity(struct game_state *game_state, + unsigned int index) { - struct entity *Entity = NULL; + struct entity *entity = NULL; - if((Index > 0) && (Index < ARRAY_SIZE(GameState->Entities))) { - Entity = &GameState->Entities[Index]; + if((index > 0) && (index < ARRAY_SIZE(game_state->entities))) { + entity = &game_state->entities[index]; } - return Entity; + return entity; } -static void InitializePlayer(struct entity *Entity) +static void initialize_player(struct entity *entity) { - Entity->Exists = 1; - Entity->P.AbsTileX = 2; - Entity->P.AbsTileY = 3; - Entity->P.Offset.X = 5.0f; - Entity->P.Offset.Y = 5.0f; - Entity->Height = 1.4f; - Entity->Width = 0.75f * Entity->Height; + entity->exists = 1; + entity->p.abs_tile_x = 2; + entity->p.abs_tile_y = 3; + entity->p.offset.x = 5.0f; + entity->p.offset.y = 5.0f; + entity->height = 1.4f; + entity->width = 0.75f * entity->height; } -static unsigned int AddEntity(struct game_state *GameState) +static unsigned int add_entity(struct game_state *game_state) { - unsigned int EntityIndex = ++GameState->EntityCount; - struct entity *Entity; + unsigned int entity_index = ++game_state->entity_count; + struct entity *entity; - ASSERT(GameState->EntityCount < ARRAY_SIZE(GameState->Entities)); - Entity = &GameState->Entities[EntityIndex]; - memset(Entity, 0, sizeof(struct entity)); + assert(game_state->entity_count < ARRAY_SIZE(game_state->entities)); + entity = &game_state->entities[entity_index]; + memset(entity, 0, sizeof(struct entity)); - return EntityIndex; + return entity_index; } -static void MovePlayer(struct game_state *GameState, - struct entity *Entity, float dt, struct v2 ddPlayer) +static void move_player(struct game_state *game_state, + struct entity *entity, float dt, + struct v2 dd_player) { - struct tile_map *TileMap; + struct tile_map *tile_map; - float PlayerSpeed; + float player_speed; - struct tile_map_position OldPlayerP, NewPlayerP; - struct v2 PlayerDelta; + struct tile_map_position old_player_p, new_player_p; + struct v2 player_delta; - TileMap = GameState->World->TileMap; + tile_map = game_state->world->tile_map; - if((ddPlayer.X != 0.0f) && (ddPlayer.Y != 0.0f)) - ddPlayer = V2Multiply(0.7071067811865475244f, ddPlayer); + if((dd_player.x != 0.0f) && (dd_player.y != 0.0f)) + dd_player = V2Multiply(0.7071067811865475244f, dd_player); - PlayerSpeed = 10.0f; - ddPlayer = V2Multiply(PlayerSpeed, ddPlayer); + player_speed = 10.0f; + dd_player = V2Multiply(player_speed, dd_player); - ddPlayer = V2Add(ddPlayer, V2Unary(V2Multiply(1.5f, Entity->dP))); + dd_player = V2Add(dd_player, V2Unary(V2Multiply(1.5f, entity->dp))); - OldPlayerP = Entity->P; - NewPlayerP = OldPlayerP; - PlayerDelta = V2Add(V2Multiply(0.5f, V2Multiply(Square(dt), ddPlayer)), - V2Multiply(dt, Entity->dP)); - NewPlayerP.Offset = V2Add(PlayerDelta, NewPlayerP.Offset); - Entity->dP = V2Add(V2Multiply(dt, ddPlayer), Entity->dP); - NewPlayerP = RecannonicalizePosition(TileMap, NewPlayerP); + old_player_p = entity->p; + new_player_p = old_player_p; + player_delta = V2Add(V2Multiply(0.5f, V2Multiply(Square(dt), dd_player)), + V2Multiply(dt, entity->dp)); + new_player_p.offset = V2Add(player_delta, new_player_p.offset); + entity->dp = V2Add(V2Multiply(dt, dd_player), entity->dp); + new_player_p = recannonicalize_position(tile_map, new_player_p); { #if 1 - struct tile_map_position PlayerLeft, PlayerRight; + struct tile_map_position player_left, player_right; - int Collided; + int collided; - struct tile_map_position ColP; + struct tile_map_position col_p; - PlayerLeft = NewPlayerP; - PlayerLeft.Offset.X -= 0.5f*Entity->Width; - PlayerLeft = RecannonicalizePosition(TileMap, PlayerLeft); + player_left = new_player_p; + player_left.offset.x -= 0.5f*entity->width; + player_left = recannonicalize_position(tile_map, player_left); - PlayerRight = NewPlayerP; - PlayerRight.Offset.X += 0.5f*Entity->Width; - PlayerRight = RecannonicalizePosition(TileMap, PlayerRight); + player_right = new_player_p; + player_right.offset.x += 0.5f*entity->width; + player_right = recannonicalize_position(tile_map, player_right); - Collided = 0; - memset(&ColP, 0, sizeof(ColP)); - if(!IsTileMapPointEmpty(TileMap, NewPlayerP)) { - ColP = NewPlayerP; - Collided = 1; + collided = 0; + memset(&col_p, 0, sizeof(col_p)); + if(!is_tile_map_point_empty(tile_map, new_player_p)) { + col_p = new_player_p; + collided = 1; } - if(!IsTileMapPointEmpty(TileMap, PlayerLeft)) { - ColP = PlayerLeft; - Collided = 1; + if(!is_tile_map_point_empty(tile_map, player_left)) { + col_p = player_left; + collided = 1; } - if(!IsTileMapPointEmpty(TileMap, PlayerRight)) { - ColP = PlayerRight; - Collided = 1; + if(!is_tile_map_point_empty(tile_map, player_right)) { + col_p = player_right; + collided = 1; } - if(Collided) { + if(collided) { struct v2 r = { 0, 0 }; - if(ColP.AbsTileX < Entity->P.AbsTileX) { - r.X = 1; - r.Y = 0; + if(col_p.abs_tile_x < entity->p.abs_tile_x) { + r.x = 1; + r.y = 0; } - if(ColP.AbsTileX > Entity->P.AbsTileX) { - r.X = -1; - r.Y = 0; + if(col_p.abs_tile_x > entity->p.abs_tile_x) { + r.x = -1; + r.y = 0; } - if(ColP.AbsTileY < Entity->P.AbsTileY) { - r.X = 0; - r.Y = 1; + if(col_p.abs_tile_y < entity->p.abs_tile_y) { + r.x = 0; + r.y = 1; } - if(ColP.AbsTileY > Entity->P.AbsTileY) { - r.X = 0; - r.Y = -1; + if(col_p.abs_tile_y > entity->p.abs_tile_y) { + r.x = 0; + r.y = -1; } - Entity->dP = V2Subtract(Entity->dP, - V2Multiply(1*InnerProduct(Entity->dP, r), r)); + entity->dp = V2Subtract(entity->dp, + V2Multiply(1*InnerProduct(entity->dp, r), r)); } else { - Entity->P = NewPlayerP; + entity->p = new_player_p; } #else unsigned int MinTileX = 0; unsigned int MinTileY = 0; unsigned int OnePastMaxTileX = 0; unsigned int OnePastMaxTileY = 0; - unsigned int AbsTileZ = GameState->PlayerP.AbsTileZ; - tile_map_position BestPlayerP = GameState->PlayerP; - F32 BestDistance = LengthSq(PlayerDelta); - for(unsigned int AbsTileY = MinTileY; - AbsTileY != OnePastMaxTileY; - AbsTileY++) + unsigned int abs_tile_z = game_state->PlayerP.abs_tile_z; + tile_map_position BestPlayerP = game_state->PlayerP; + F32 BestDistance = LengthSq(player_delta); + for(unsigned int abs_tile_y = MinTileY; + abs_tile_y != OnePastMaxTileY; + abs_tile_y++) { - for(unsigned int AbsTileX = MinTileX; - AbsTileX != OnePastMaxTileX; - AbsTileX++) + for(unsigned int abs_tile_x = MinTileX; + abs_tile_x != OnePastMaxTileX; + abs_tile_x++) { tile_map_position TestTileP = - CenteredTilePoint(AbsTileX, AbsTileY, AbsTileZ); - unsigned int TileValue = GetTileValueByPos(TileMap, TestTileP); + CenteredTilePoint(abs_tile_x, abs_tile_y, abs_tile_z); + unsigned int TileValue = get_tile_value_by_pos(tile_map, TestTileP); if(IsTileValueEmpty(TileValue)) { v2 MinCorner = V2Multiply(-0.5f, - (v2){ TileMap->TileSideInMeters, - TileMap->TileSideInMeters }); + (v2){ tile_map->tile_side_in_meters, + tile_map->tile_side_in_meters }); v2 MaxCorner = V2Multiply(-0.5f, - (v2){ TileMap->TileSideInMeters, - TileMap->TileSideInMeters }); + (v2){ tile_map->tile_side_in_meters, + tile_map->tile_side_in_meters }); tile_map_difference RelNewPlayerP = - SubtractInF32(TileMap, &TestTileP, &NewPlayerP); + SubtractInF32(tile_map, &TestTileP, &new_player_p); v2 TestP = ClosestPointInRectangle(MinCorner, MaxCorner, RelNewPlayerP); if(...) { @@ -442,410 +446,424 @@ static void MovePlayer(struct game_state *GameState, #endif } - if(!AreOnSameTile(&OldPlayerP, &Entity->P)) { - unsigned int NewTileValue = GetTileValueByPos(TileMap, Entity->P); + if(!are_on_same_tile(&old_player_p, &entity->p)) { + unsigned int new_tile_value = + get_tile_value_by_pos(tile_map, entity->p); - if(NewTileValue == 3) { - Entity->P.AbsTileZ++; - } else if(NewTileValue == 4) { - Entity->P.AbsTileZ--; + if(new_tile_value == 3) { + entity->p.abs_tile_z++; + } else if(new_tile_value == 4) { + entity->p.abs_tile_z--; } } - if(AbsoluteValue(ddPlayer.X) > AbsoluteValue(ddPlayer.Y)) { - if(ddPlayer.X > 0) { - Entity->FacingDirection = 0; + if(absolute_value(dd_player.x) > absolute_value(dd_player.y)) { + if(dd_player.x > 0) { + entity->facing_direction = 0; } else { - Entity->FacingDirection = 2; + entity->facing_direction = 2; } - } else if(AbsoluteValue(ddPlayer.X) < AbsoluteValue(ddPlayer.Y)) { - if(ddPlayer.Y > 0) { - Entity->FacingDirection = 1; + } else if(absolute_value(dd_player.x) < absolute_value(dd_player.y)) { + if(dd_player.y > 0) { + entity->facing_direction = 1; } else { - Entity->FacingDirection = 3; + entity->facing_direction = 3; } } } -void UpdateAndRender(struct thread_context *Thread, - struct game_memory *Memory, struct game_input *Input, - struct game_offscreen_buffer *Buffer, - struct game_sound_output_buffer *SoundBuffer) +void update_and_render(struct thread_context *thread, + struct game_memory *memory, struct game_input *input, + struct game_offscreen_buffer *buffer, + struct game_sound_output_buffer *sound_buffer) { - struct game_state *GameState; + struct game_state *game_state; - struct world *World; - struct tile_map *TileMap; + struct world *world; + struct tile_map *tile_map; - int TileSideInPixels; - float MetersToPixels; + int tile_side_in_pixels; + float meters_to_pixels; - unsigned int ControllerIndex; + unsigned int controller_index; - struct entity *CameraFollowingEntity; + struct entity *camera_following_entity; - float ScreenCenterX, ScreenCenterY; + float screen_center_x, screen_center_y; - int RelRow, RelColumn; + int rel_row, rel_column; - struct entity *Entity; + struct entity *entity; - unsigned int EntityIndex; + unsigned int entity_index; - ASSERT((&Input->Controllers[0].u.s.Terminator - - &Input->Controllers[0].u.Buttons[0]) == - ARRAY_SIZE(Input->Controllers[0].u.Buttons)); - ASSERT(sizeof(struct game_state) <= Memory->PermanentStorageSize); + assert((&input->controllers[0].u.s.terminator - + &input->controllers[0].u.buttons[0]) == + ARRAY_SIZE(input->controllers[0].u.buttons)); + assert(sizeof(struct game_state) <= memory->permanent_storage_size); - GameState = (struct game_state *)Memory->PermanentStorage; - if(!Memory->IsInitialized) { - struct hero_bitmaps *Bitmap; - struct world *World; - struct tile_map *TileMap; + game_state = (struct game_state *)memory->permanent_storage; + if(!memory->is_initialized) { + struct hero_bitmaps *bitmap; + struct world *world; + struct tile_map *tile_map; - unsigned int RandomNumberIndex; + unsigned int random_number_index; - unsigned int TilesPerWidth, TilesPerHeight; - unsigned int ScreenX, ScreenY; + unsigned int tiles_per_width, tiles_per_height; + unsigned int screen_x, screen_y; - unsigned int AbsTileZ; + unsigned int abs_tile_z; - int DoorTop, DoorBottom, DoorLeft, DoorRight, DoorUp, DoorDown; + int door_top, door_bottom, door_left, door_right, door_up, door_down; - unsigned int ScreenIndex; + unsigned int screen_index; /* NOTE: Reserve entity slot 0 for null entity */ - AddEntity(GameState); + add_entity(game_state); - GameState->rect_pos.X = 0.0f; - GameState->rect_pos.Y = 0.0f; + game_state->rect_pos.x = 0.0f; + game_state->rect_pos.y = 0.0f; - GameState->ProgramIcon.Width = 256; - GameState->ProgramIcon.Height = 256; - GameState->ProgramIcon.BytesPerPixel = 4; - GameState->ProgramIcon.Pitch = GameState->ProgramIcon.BytesPerPixel * - GameState->ProgramIcon.Width; - GameState->ProgramIcon.Memory = - malloc(GameState->ProgramIcon.BytesPerPixel * - GameState->ProgramIcon.Width * - GameState->ProgramIcon.Height); - memset(GameState->ProgramIcon.Memory, 0, - GameState->ProgramIcon.BytesPerPixel * - GameState->ProgramIcon.Width * - GameState->ProgramIcon.Height); + game_state->program_icon.width = 256; + game_state->program_icon.height = 256; + game_state->program_icon.bytes_per_pixel = 4; + game_state->program_icon.pitch = + game_state->program_icon.bytes_per_pixel * + game_state->program_icon.width; + game_state->program_icon.memory = + malloc(game_state->program_icon.bytes_per_pixel * + game_state->program_icon.width * + game_state->program_icon.height); + memset(game_state->program_icon.memory, 0, + game_state->program_icon.bytes_per_pixel * + game_state->program_icon.width * + game_state->program_icon.height); #if 0 - GameState->ProgramIconBMP = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, "data/program_icon.bmp"); - DrawBitmap(&GameState->ProgramIcon, &GameState->ProgramIconBMP, + game_state->ProgramIconBMP = debug_load_bmp(thread, + memory->DEBUGPlatformReadEntireFile, "data/program_icon.bmp"); + draw_bitmap(&game_state->ProgramIcon, &game_state->ProgramIconBMP, 0.0f, 0.0f, 0, 0); - Memory->SetProgramIcon(&GameState->ProgramIcon); + memory->SetProgramIcon(&game_state->ProgramIcon); #endif - GameState->Backdrop = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, "data/test_background.bmp"); + game_state->backdrop = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_background.bmp"); - Bitmap = &GameState->HeroBitmaps[0]; - Bitmap->AlignX = 72; - Bitmap->AlignY = 182; - Bitmap->Head = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_right_head.bmp"); - Bitmap->Cape = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_right_cape.bmp"); - Bitmap->Torso = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_right_torso.bmp"); - Bitmap++; + bitmap = &game_state->hero_bitmaps[0]; + bitmap->align_x = 72; + bitmap->align_y = 182; + bitmap->head = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_right_head.bmp"); + bitmap->cape = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_right_cape.bmp"); + bitmap->torso = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_right_torso.bmp"); + bitmap++; - Bitmap->AlignX = 72; - Bitmap->AlignY = 182; - Bitmap->Head = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_back_head.bmp"); - Bitmap->Cape = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_back_cape.bmp"); - Bitmap->Torso = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_back_torso.bmp"); - Bitmap++; + bitmap->align_x = 72; + bitmap->align_y = 182; + bitmap->head = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_back_head.bmp"); + bitmap->cape = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_back_cape.bmp"); + bitmap->torso = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_back_torso.bmp"); + bitmap++; - Bitmap->AlignX = 72; - Bitmap->AlignY = 182; - Bitmap->Head = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_left_head.bmp"); - Bitmap->Cape = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_left_cape.bmp"); - Bitmap->Torso = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_left_torso.bmp"); - Bitmap++; + bitmap->align_x = 72; + bitmap->align_y = 182; + bitmap->head = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_left_head.bmp"); + bitmap->cape = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_left_cape.bmp"); + bitmap->torso = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_left_torso.bmp"); + bitmap++; - Bitmap->AlignX = 72; - Bitmap->AlignY = 182; - Bitmap->Head = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_front_head.bmp"); - Bitmap->Cape = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_front_cape.bmp"); - Bitmap->Torso = DEBUGLoadBMP(Thread, - Memory->DEBUGPlatformReadEntireFile, - "data/test_hero_front_torso.bmp"); + bitmap->align_x = 72; + bitmap->align_y = 182; + bitmap->head = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_front_head.bmp"); + bitmap->cape = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_front_cape.bmp"); + bitmap->torso = debug_load_bmp(thread, + memory->debug_platform_read_entire_file, + "data/test_hero_front_torso.bmp"); - GameState->CameraP.AbsTileX = 17 / 2; - GameState->CameraP.AbsTileY = 9 / 2; + game_state->camera_p.abs_tile_x = 17 / 2; + game_state->camera_p.abs_tile_y = 9 / 2; - InitializeArena(&GameState->WorldArena, - Memory->PermanentStorageSize - sizeof(struct game_state), - (unsigned char *)Memory->PermanentStorage + + InitializeArena(&game_state->world_arena, + memory->permanent_storage_size - sizeof(struct game_state), + (unsigned char *)memory->permanent_storage + sizeof(struct game_state)); - GameState->World = PUSH_STRUCT(&GameState->WorldArena, struct world); - World = GameState->World; - World->TileMap = PUSH_STRUCT(&GameState->WorldArena, struct tile_map); + game_state->world = + PUSH_STRUCT(&game_state->world_arena, struct world); + world = game_state->world; + world->tile_map = + PUSH_STRUCT(&game_state->world_arena, struct tile_map); - TileMap = World->TileMap; + tile_map = world->tile_map; - TileMap->ChunkShift = 4; - TileMap->ChunkMask = (1 << TileMap->ChunkShift) - 1; - TileMap->ChunkDim = (1 << TileMap->ChunkShift); + tile_map->chunk_shift = 4; + tile_map->chunk_mask = (1 << tile_map->chunk_shift) - 1; + tile_map->chunk_dim = (1 << tile_map->chunk_shift); - TileMap->TileChunkCountX = 128; - TileMap->TileChunkCountY = 128; - TileMap->TileChunkCountZ = 2; + tile_map->tile_chunk_count_x = 128; + tile_map->tile_chunk_count_y = 128; + tile_map->tile_chunk_count_z = 2; - TileMap->TileChunks = PUSH_ARRAY(&GameState->WorldArena, - TileMap->TileChunkCountX * TileMap->TileChunkCountY * - TileMap->TileChunkCountZ, + tile_map->tile_chunks = PUSH_ARRAY(&game_state->world_arena, + tile_map->tile_chunk_count_x * tile_map->tile_chunk_count_y * + tile_map->tile_chunk_count_z, struct tile_chunk); - TileMap->TileSideInMeters = 1.4f; + tile_map->tile_side_in_meters = 1.4f; - RandomNumberIndex = 0; + random_number_index = 0; - TilesPerWidth = 17; - TilesPerHeight = 9; - ScreenX = 0; - ScreenY = 0; + tiles_per_width = 17; + tiles_per_height = 9; + screen_x = 0; + screen_y = 0; - AbsTileZ = 0; + abs_tile_z = 0; - DoorTop = 0; - DoorBottom = 0; - DoorLeft = 0; - DoorRight = 0; - DoorUp = 0; - DoorDown = 0; - for(ScreenIndex = 0; ScreenIndex < 100; ScreenIndex++) { + door_top = 0; + door_bottom = 0; + door_left = 0; + door_right = 0; + door_up = 0; + door_down = 0; + for(screen_index = 0; screen_index < 100; screen_index++) { /* TODO: Random number generator. */ - unsigned int RandomChoice; + unsigned int random_choice; - int CreatedZDoor; + int created_z_door; - unsigned int TileY, TileX; + unsigned int tile_y, tile_x; - ASSERT(RandomNumberIndex < ARRAY_SIZE(RandomNumberTable)); + assert(random_number_index < ARRAY_SIZE(random_number_table)); - if(DoorUp || DoorDown) { - RandomChoice = RandomNumberTable[RandomNumberIndex++] % 2; + if(door_up || door_down) { + random_choice = + random_number_table[random_number_index++] % 2; } else { - RandomChoice = RandomNumberTable[RandomNumberIndex++] % 3; + random_choice = + random_number_table[random_number_index++] % 3; } - CreatedZDoor = 0; + created_z_door = 0; - if(RandomChoice == 2) { - CreatedZDoor = 1; + if(random_choice == 2) { + created_z_door = 1; - if(AbsTileZ == 0) { - DoorUp = 1; + if(abs_tile_z == 0) { + door_up = 1; } else { - DoorDown = 1; + door_down = 1; } - } else if(RandomChoice == 1) { - DoorRight = 1; + } else if(random_choice == 1) { + door_right = 1; } else { - DoorTop = 1; + door_top = 1; } - for(TileY = 0; TileY < TilesPerHeight; TileY++) { - for(TileX = 0; TileX < TilesPerWidth; TileX++) { - unsigned int AbsTileX = ScreenX * TilesPerWidth + TileX; - unsigned int AbsTileY = ScreenY * TilesPerHeight + TileY; + for(tile_y = 0; tile_y < tiles_per_height; tile_y++) { + for(tile_x = 0; tile_x < tiles_per_width; tile_x++) { + unsigned int abs_tile_x = + screen_x * tiles_per_width + tile_x; + unsigned int abs_tile_y = + screen_y * tiles_per_height + tile_y; unsigned int TileValue = 1; - if(TileX == 0 && - (!DoorLeft || (TileY != (TilesPerHeight/2)))) + if(tile_x == 0 && + (!door_left || (tile_y != (tiles_per_height/2)))) { TileValue = 2; } - if(TileX == (TilesPerWidth - 1) && - (!DoorRight || (TileY != (TilesPerHeight/2)))) + if(tile_x == (tiles_per_width - 1) && + (!door_right || (tile_y != (tiles_per_height/2)))) { TileValue = 2; } - if(TileY == 0 && - (!DoorBottom || (TileX != (TilesPerWidth/2)))) + if(tile_y == 0 && + (!door_bottom || (tile_x != (tiles_per_width/2)))) { TileValue = 2; } - if(TileY == (TilesPerHeight - 1) && - (!DoorTop || (TileX != (TilesPerWidth/2)))) + if(tile_y == (tiles_per_height - 1) && + (!door_top || (tile_x != (tiles_per_width/2)))) { TileValue = 2; } - if((TileX == 10) && (TileY == 6)) { - if(DoorUp) { + if((tile_x == 10) && (tile_y == 6)) { + if(door_up) { TileValue = 3; } - if(DoorDown) { + if(door_down) { TileValue = 4; } } - SetTileValue(&GameState->WorldArena, World->TileMap, - AbsTileX, AbsTileY, AbsTileZ, TileValue); + set_tile_value(&game_state->world_arena, world->tile_map, + abs_tile_x, abs_tile_y, abs_tile_z, + TileValue); } } - DoorLeft = DoorRight; - DoorBottom = DoorTop; + door_left = door_right; + door_bottom = door_top; - if(CreatedZDoor) { - DoorDown = !DoorDown; - DoorUp = !DoorUp; + if(created_z_door) { + door_down = !door_down; + door_up = !door_up; } else { - DoorUp = 0; - DoorDown = 0; + door_up = 0; + door_down = 0; } - DoorTop = 0; - DoorRight = 0; + door_top = 0; + door_right = 0; - if(RandomChoice == 2) { - if(AbsTileZ == 0) { - AbsTileZ = 1; + if(random_choice == 2) { + if(abs_tile_z == 0) { + abs_tile_z = 1; } else { - AbsTileZ = 0; + abs_tile_z = 0; } - } else if(RandomChoice == 1) { - ScreenX++; + } else if(random_choice == 1) { + screen_x++; } else { - ScreenY++; + screen_y++; } } - Memory->IsInitialized = 1; + memory->is_initialized = 1; } - World = GameState->World; - TileMap = World->TileMap; + world = game_state->world; + tile_map = world->tile_map; - TileSideInPixels = 60; - MetersToPixels = (float)TileSideInPixels / TileMap->TileSideInMeters; + tile_side_in_pixels = 60; + meters_to_pixels = + (float)tile_side_in_pixels / tile_map->tile_side_in_meters; - for(ControllerIndex = 0; - ControllerIndex < ARRAY_SIZE(Input->Controllers); - ControllerIndex++) + for(controller_index = 0; + controller_index < ARRAY_SIZE(input->controllers); + controller_index++) { struct game_controller_input *Controller; struct entity *ControllingEntity; - Controller = GetController(Input, ControllerIndex); - ControllingEntity = GetEntity(GameState, - GameState->PlayerIndexForController[ControllerIndex]); + Controller = GetController(input, controller_index); + ControllingEntity = get_entity(game_state, + game_state->player_index_for_controller[controller_index]); if(ControllingEntity) { - struct v2 ddPlayer; /* accerlation */ - memset(&ddPlayer, 0, sizeof(ddPlayer)); + struct v2 dd_player; /* accerlation */ + memset(&dd_player, 0, sizeof(dd_player)); - if(Controller->IsAnalog) { - ddPlayer.X = Controller->StickAverageX; - ddPlayer.Y = -Controller->StickAverageY; + if(Controller->is_analog) { + dd_player.x = Controller->stick_average_x; + dd_player.y = -Controller->stick_average_y; } else { - if(Controller->u.s.MoveUp.EndedDown) { - GameState->rect_pos.Y -= 1.0f; + if(Controller->u.s.move_up.ended_down) { + game_state->rect_pos.y -= 1.0f; - ddPlayer.Y = 1.0f; + dd_player.y = 1.0f; } - if(Controller->u.s.MoveDown.EndedDown) { - GameState->rect_pos.Y += 1.0f; + if(Controller->u.s.move_down.ended_down) { + game_state->rect_pos.y += 1.0f; - ddPlayer.Y = -1.0f; + dd_player.y = -1.0f; } - if(Controller->u.s.MoveLeft.EndedDown) { - GameState->rect_pos.X -= 1.0f; + if(Controller->u.s.move_left.ended_down) { + game_state->rect_pos.x -= 1.0f; - ddPlayer.X = -1.0f; + dd_player.x = -1.0f; } - if(Controller->u.s.MoveRight.EndedDown) { - GameState->rect_pos.X += 1.0f; + if(Controller->u.s.move_right.ended_down) { + game_state->rect_pos.x += 1.0f; - ddPlayer.X = 1.0f; + dd_player.x = 1.0f; } } - MovePlayer(GameState, ControllingEntity, Input->dtForFrame, - ddPlayer); + move_player(game_state, ControllingEntity, input->dt_for_frame, + dd_player); } else { - if(Controller->u.s.Start.EndedDown) { - unsigned int EntityIndex = AddEntity(GameState); - ControllingEntity = GetEntity(GameState, EntityIndex); - InitializePlayer(ControllingEntity); - GameState->PlayerIndexForController[ControllerIndex] = - EntityIndex; + if(Controller->u.s.start.ended_down) { + unsigned int entity_index = add_entity(game_state); + ControllingEntity = get_entity(game_state, entity_index); + initialize_player(ControllingEntity); + game_state->player_index_for_controller[controller_index] = + entity_index; } } } - CameraFollowingEntity = - GetEntity(GameState, GameState->CameraFollowingEntityIndex); - if(CameraFollowingEntity) { - struct tile_map_difference Diff; + camera_following_entity = + get_entity(game_state, game_state->camera_following_entity_index); + if(camera_following_entity) { + struct tile_map_difference diff; - GameState->CameraP.AbsTileZ = CameraFollowingEntity->P.AbsTileZ; + game_state->camera_p.abs_tile_z = + camera_following_entity->p.abs_tile_z; - Diff = SubtractInFloat(TileMap, &CameraFollowingEntity->P, - &GameState->CameraP); - if(Diff.dXY.X > (9.0f*TileMap->TileSideInMeters)) { - GameState->CameraP.AbsTileX += 17; + diff = subtract_in_float(tile_map, &camera_following_entity->p, + &game_state->camera_p); + if(diff.d_xy.x > (9.0f*tile_map->tile_side_in_meters)) { + game_state->camera_p.abs_tile_x += 17; } - if(Diff.dXY.X < -(9.0f*TileMap->TileSideInMeters)) { - GameState->CameraP.AbsTileX -= 17; + if(diff.d_xy.x < -(9.0f*tile_map->tile_side_in_meters)) { + game_state->camera_p.abs_tile_x -= 17; } - if(Diff.dXY.Y > (5.0f*TileMap->TileSideInMeters)) { - GameState->CameraP.AbsTileY += 9; + if(diff.d_xy.y > (5.0f*tile_map->tile_side_in_meters)) { + game_state->camera_p.abs_tile_y += 9; } - if(Diff.dXY.Y < -(5.0f*TileMap->TileSideInMeters)) { - GameState->CameraP.AbsTileY -= 9; + if(diff.d_xy.y < -(5.0f*tile_map->tile_side_in_meters)) { + game_state->camera_p.abs_tile_y -= 9; } } - /*DrawRectangle(Buffer, 0.0f, 0.0f, - (F32)Buffer->Width, (F32)Buffer->Height, + /*draw_rectangle(buffer, 0.0f, 0.0f, + (F32)buffer->Width, (F32)buffer->Height, 0.0f, 1.0f, 0.0f);*/ - DrawBitmap(Buffer, &GameState->Backdrop, 0.0f, 0.0f, 0, 0); + draw_bitmap(buffer, &game_state->backdrop, 0.0f, 0.0f, 0, 0); - ScreenCenterX = 0.5f * (float)Buffer->Width; - ScreenCenterY = 0.5f * (float)Buffer->Height; + screen_center_x = 0.5f * (float)buffer->width; + screen_center_y = 0.5f * (float)buffer->height; - for(RelRow = -10; RelRow < 10; RelRow++) { - for(RelColumn = -20; RelColumn < 20; RelColumn++) { - unsigned int Column = GameState->CameraP.AbsTileX + RelColumn; - unsigned int Row = GameState->CameraP.AbsTileY + RelRow; + for(rel_row = -10; rel_row < 10; rel_row++) { + for(rel_column = -20; rel_column < 20; rel_column++) { + unsigned int Column = + game_state->camera_p.abs_tile_x + rel_column; + unsigned int row = + game_state->camera_p.abs_tile_y + rel_row; - unsigned int TileID = GetTileValue(TileMap, Column, Row, - GameState->CameraP.AbsTileZ); + unsigned int TileID = get_tile_value(tile_map, Column, row, + game_state->camera_p.abs_tile_z); if(TileID > 1) { struct v2 TileSide, Center; @@ -862,112 +880,116 @@ void UpdateAndRender(struct thread_context *Thread, Gray = 0.25f; } - if(Column == GameState->CameraP.AbsTileX && - Row == GameState->CameraP.AbsTileY) + if(Column == game_state->camera_p.abs_tile_x && + row == game_state->camera_p.abs_tile_y) { Gray = 0.0f; } - TileSide.X = 0.5f*(float)TileSideInPixels; - TileSide.Y = 0.5f*(float)TileSideInPixels; - Center.X = ScreenCenterX - - MetersToPixels*GameState->CameraP.Offset.X + - (float)RelColumn*(float)TileSideInPixels; - Center.Y = ScreenCenterY + MetersToPixels * - GameState->CameraP.Offset.Y - - (float)RelRow*(float)TileSideInPixels; + TileSide.x = 0.5f*(float)tile_side_in_pixels; + TileSide.y = 0.5f*(float)tile_side_in_pixels; + Center.x = screen_center_x - + meters_to_pixels*game_state->camera_p.offset.x + + (float)rel_column*(float)tile_side_in_pixels; + Center.y = screen_center_y + meters_to_pixels * + game_state->camera_p.offset.y - + (float)rel_row*(float)tile_side_in_pixels; Min = V2Subtract(Center, TileSide); Max = V2Add(Center, TileSide); - DrawRectangle(Buffer, Min, Max, Gray, Gray, Gray); + draw_rectangle(buffer, Min, Max, Gray, Gray, Gray); } } } - Entity = GameState->Entities; + entity = game_state->entities; - for(EntityIndex = 0; - EntityIndex < GameState->EntityCount; - EntityIndex++, Entity++) + for(entity_index = 0; + entity_index < game_state->entity_count; + entity_index++, entity++) { - if(Entity->Exists) { - struct tile_map_difference Diff; + if(entity->exists) { + struct tile_map_difference diff; - float PlayerR, PlayerG, PlayerB; - float PlayerGroundPointX, PlayerGroundPointY; - struct v2 PlayerLeftTop, PlayerWidthHeight; + float player_r, player_g, player_b; + float player_ground_point_x, player_ground_point_y; + struct v2 player_left_top, player_width_height; - struct hero_bitmaps *Bitmap; + struct hero_bitmaps *bitmap; - Diff = SubtractInFloat(TileMap, &Entity->P, &GameState->CameraP); + diff = subtract_in_float(tile_map, &entity->p, + &game_state->camera_p); - PlayerR = 1.0f; - PlayerG = 0.0f; - PlayerB = 0.0f; - PlayerGroundPointX = ScreenCenterX + MetersToPixels*Diff.dXY.X; - PlayerGroundPointY = ScreenCenterY - MetersToPixels*Diff.dXY.Y; + player_r = 1.0f; + player_g = 0.0f; + player_b = 0.0f; + player_ground_point_x = + screen_center_x + meters_to_pixels*diff.d_xy.x; + player_ground_point_y = + screen_center_y - meters_to_pixels*diff.d_xy.y; - PlayerLeftTop.X = - PlayerGroundPointX - 0.5f * MetersToPixels*Entity->Width; - PlayerLeftTop.Y = - PlayerGroundPointY - MetersToPixels*Entity->Height; + player_left_top.x = + player_ground_point_x - 0.5f * + meters_to_pixels*entity->width; + player_left_top.y = + player_ground_point_y - meters_to_pixels*entity->height; - PlayerWidthHeight.X = Entity->Width; - PlayerWidthHeight.X = Entity->Height; + player_width_height.x = entity->width; + player_width_height.x = entity->height; - DrawRectangle(Buffer, PlayerLeftTop, - V2Add(PlayerLeftTop, V2Multiply(MetersToPixels, - PlayerWidthHeight)), - PlayerR, PlayerG, PlayerB); + draw_rectangle(buffer, player_left_top, + V2Add(player_left_top, V2Multiply(meters_to_pixels, + player_width_height)), + player_r, player_g, player_b); - Bitmap = &GameState->HeroBitmaps[Entity->FacingDirection]; - DrawBitmap(Buffer, &Bitmap->Torso, - PlayerGroundPointX, PlayerGroundPointY, - Bitmap->AlignX, Bitmap->AlignY); - DrawBitmap(Buffer, &Bitmap->Cape, - PlayerGroundPointX, PlayerGroundPointY, - Bitmap->AlignX, Bitmap->AlignY); - DrawBitmap(Buffer, &Bitmap->Head, - PlayerGroundPointX, PlayerGroundPointY, - Bitmap->AlignX, Bitmap->AlignY); + bitmap = &game_state->hero_bitmaps[entity->facing_direction]; + draw_bitmap(buffer, &bitmap->torso, + player_ground_point_x, player_ground_point_y, + bitmap->align_x, bitmap->align_y); + draw_bitmap(buffer, &bitmap->cape, + player_ground_point_x, player_ground_point_y, + bitmap->align_x, bitmap->align_y); + draw_bitmap(buffer, &bitmap->head, + player_ground_point_x, player_ground_point_y, + bitmap->align_x, bitmap->align_y); /* TODO: Remove this. */ - /*DrawRectangle(&GameState->ProgramIcon, GameState->rect_pos, - (struct v2){ GameState->rect_pos.X + 20.0f, - GameState->rect_pos.Y + 20.0f }, + /*draw_rectangle(&game_state->ProgramIcon, game_state->rect_pos, + (struct v2){ game_state->rect_pos.X + 20.0f, + game_state->rect_pos.Y + 20.0f }, 0.8f, 0.8f, 0.8f);*/ - /*Memory->SetProgramIcon(&GameState->ProgramIcon);*/ + /*memory->SetProgramIcon(&game_state->ProgramIcon);*/ } } - GameOutputSound(GameState, SoundBuffer, 400); + game_output_sound(game_state, sound_buffer, 400); } /* -static void RenderWeirdGradient(game_offscreen_buffer *Buffer, +static void RenderWeirdGradient(game_offscreen_buffer *buffer, int XOffset, int YOffset) { int Width, Height, Y; - U8 *Row; + U8 *row; - Width = Buffer->Width; - Height = Buffer->Height; + Width = buffer->Width; + Height = buffer->Height; - Row = (U8 *)Buffer->Memory; + row = (U8 *)buffer->memory; for(Y = 0; Y < Height; Y++) { - unsigned int *Pixel = (unsigned int *)Row; + unsigned int *pixel = (unsigned int *)row; int X; - Pixel = (unsigned int *)Row; + pixel = (unsigned int *)row; for(X = 0; X < Width; X++) { U8 Blue, Green; Blue = (U8)(X + XOffset); Green = (U8)(Y + YOffset); - *Pixel = (Green << 8) | Blue; - Pixel++; + *pixel = (Green << 8) | Blue; + pixel++; } - Row += Buffer->Pitch; + row += buffer->Pitch; } } */ diff --git a/handmade.h b/handmade.h index 6653499..3de4b6a 100644 --- a/handmade.h +++ b/handmade.h @@ -1,34 +1,37 @@ #ifndef HANDMADE_H_SENTRY #define HANDMADE_H_SENTRY -#include "core.h" +#include "helpers.h" + #include "handmade_tile.h" + +#include + /* --------------------------------------------------------------------- */ /* NOTE: Servcies that the platform layer provides to the game. */ /* --------------------------------------------------------------------- */ struct thread_context { - int Placeholder; + int placeholder; }; -#if BUILD_INTERNAL struct debug_read_file_result { - unsigned int ContentsSize; - void *Contents; + unsigned int contents_size; + void *contents; }; struct debug_read_file_result - DEBUGPlatformReadEntireFile(struct thread_context *Thread, - const char *Filename); -int DEBUGPlatformWriteEntireFile(struct thread_context *Thread, - const char *Filename, - unsigned int MemorySize, void *Memory); -void DEBUGPlatformFreeFileMemory(struct thread_context *Thread, - void *Memory); -#endif + debug_platform_read_entire_file(struct thread_context *thread, + const char *filename); +int debug_platform_write_entire_file(struct thread_context *thread, + const char *filename, + unsigned int memory_size, + void *memory); +void debug_platform_free_file_memory(struct thread_context *thread, + void *memory); struct game_offscreen_buffer game_offscreen_buffer; -void SetProgramIcon(struct game_offscreen_buffer *ProgramIcon); +void set_program_icon(struct game_offscreen_buffer *program_icon); /* --------------------------------------------------------------------- */ /* NOTE: Servcies that the game provides to the platform layer. */ @@ -36,64 +39,64 @@ void SetProgramIcon(struct game_offscreen_buffer *ProgramIcon); struct game_offscreen_buffer { /* Pixels are always 32-bit and have the bytes in BGRX (little-endian). */ - void *Memory; - int Width; - int Height; - int BytesPerPixel; - int Pitch; + void *memory; + int width; + int height; + int bytes_per_pixel; + int pitch; }; struct game_sound_output_buffer { - int SamplesPerSecond; - int SampleCount; - short *Samples; + int samples_per_second; + int sample_count; + short *samples; }; struct game_button_state { - int HalfTransitionCount; - int EndedDown; + int half_transition_count; + int ended_down; }; struct game_controller_input { - int IsConnected; - int IsAnalog; + int is_connected; + int is_analog; - float StickAverageX; - float StickAverageY; + float stick_average_x; + float stick_average_y; union { - struct game_button_state Buttons[12]; + struct game_button_state buttons[12]; struct { - struct game_button_state MoveUp; - struct game_button_state MoveDown; - struct game_button_state MoveLeft; - struct game_button_state MoveRight; + struct game_button_state move_up; + struct game_button_state move_down; + struct game_button_state move_left; + struct game_button_state move_right; - struct game_button_state ActionUp; - struct game_button_state ActionDown; - struct game_button_state ActionLeft; - struct game_button_state ActionRight; + struct game_button_state action_up; + struct game_button_state action_down; + struct game_button_state action_left; + struct game_button_state action_right; - struct game_button_state LeftShoulder; - struct game_button_state RightShoulder; + struct game_button_state left_shoulder; + struct game_button_state right_shoulder; - struct game_button_state Start; - struct game_button_state Back; + struct game_button_state start; + struct game_button_state back; /* NOTE: All buttons must be added above this line. */ - struct game_button_state Terminator; + struct game_button_state terminator; } s; } u; }; struct game_input { - struct game_button_state MouseButtons[5]; - int MouseX, MouseY, MouseZ; /* NOTE: MouseZ is the wheel. */ + struct game_button_state mouse_buttons[5]; + int mouse_x, mouse_y, mouse_z; /* NOTE: MouseZ is the wheel. */ - float dtForFrame; + float dt_for_frame; - struct game_controller_input Controllers[5]; + struct game_controller_input controllers[5]; }; struct game_controller_input *GetController(struct game_input *Input, @@ -101,32 +104,31 @@ struct game_controller_input *GetController(struct game_input *Input, { struct game_controller_input *Result; - ASSERT((unsigned int)ControllerIndex < ARRAY_SIZE(Input->Controllers)); - Result = &(Input->Controllers[ControllerIndex]); + assert((unsigned int)ControllerIndex < ARRAY_SIZE(Input->controllers)); + Result = &(Input->controllers[ControllerIndex]); return Result; } struct game_memory { - int IsInitialized; + int is_initialized; - unsigned long long PermanentStorageSize; - void *PermanentStorage; /* WARNING: This memory is REQUIRED to be zero - initialized!!! (Done by the OS layer.) */ + unsigned long long permanent_storage_size; + void *permanent_storage; /* WARNING: This memory is REQUIRED to be zero + initialized!!! (Done by the OS layer.) */ - unsigned long long TransientStorageSize; - void *TransientStorage; /* WARNING: This memory is REQUIRED to be zero - initialized!!! (Done by the OS layer.) */ + unsigned long long transient_storage_size; + void *transient_storage; /* WARNING: This memory is REQUIRED to be zero + initialized!!! (Done by the OS layer.) */ -#if BUILD_INTERNAL struct debug_read_file_result - (*DEBUGPlatformReadEntireFile)(struct thread_context *Thread, - const char *); - int (*DEBUGPlatformWriteEntireFile)(struct thread_context *Thread, - const char *, unsigned int, void *); - void (*DEBUGPlatformFreeFileMemory)(struct thread_context *Thread, - void *); + (*debug_platform_read_entire_file)(struct thread_context *Thread, + const char *); + int (*debug_platform_write_entire_file)(struct thread_context *Thread, + const char *, unsigned int, + void *); + void (*debug_platform_free_file_memory)(struct thread_context *Thread, + void *); void (*SetProgramIcon)(struct game_offscreen_buffer *ProgramIcon); -#endif }; /*struct game_clocks { @@ -148,17 +150,17 @@ void UpdateAndRender(struct thread_context *Thread, */ struct memory_arena { - unsigned long long Size; - unsigned char *Base; - unsigned long long Used; + unsigned long long size; + unsigned char *base; + unsigned long long used; }; -static void InitializeArena(struct memory_arena *Arena, - unsigned long long Size, unsigned char *Base) +static void InitializeArena(struct memory_arena *arena, + unsigned long long size, unsigned char *base) { - Arena->Size = Size; - Arena->Base = Base; - Arena->Used = 0; + arena->size = size; + arena->base = base; + arena->used = 0; } #define PUSH_STRUCT(Arena, type) (type *)PushSize_(Arena, sizeof(type)) @@ -168,59 +170,59 @@ static void *PushSize_(struct memory_arena *Arena, unsigned long long Size) { void *Result; - ASSERT((Arena->Used + Size) <= Arena->Size); + assert((Arena->used + Size) <= Arena->size); - Result = (void *)(Arena->Base + Arena->Used); - Arena->Used += Size; + Result = (void *)(Arena->base + Arena->used); + Arena->used += Size; return Result; } struct world { - struct tile_map *TileMap; + struct tile_map *tile_map; }; struct loaded_bitmap { - int Width; - int Height; - unsigned int *Pixels; + int width; + int height; + unsigned int *pixels; }; struct hero_bitmaps { - int AlignX; - int AlignY; + int align_x; + int align_y; - struct loaded_bitmap Head; - struct loaded_bitmap Cape; - struct loaded_bitmap Torso; + struct loaded_bitmap head; + struct loaded_bitmap cape; + struct loaded_bitmap torso; }; struct entity { - int Exists; - struct tile_map_position P; - struct v2 dP; /* velocity */ - unsigned int FacingDirection; - float Height, Width; + int exists; + struct tile_map_position p; + struct v2 dp; /* velocity */ + unsigned int facing_direction; + float height, width; }; struct game_state { - struct game_offscreen_buffer ProgramIcon; - struct loaded_bitmap ProgramIconBMP; + struct game_offscreen_buffer program_icon; + struct loaded_bitmap program_icon_bmp; - struct memory_arena WorldArena; - struct world *World; + struct memory_arena world_arena; + struct world *world; - unsigned int CameraFollowingEntityIndex; - struct tile_map_position CameraP; + unsigned int camera_following_entity_index; + struct tile_map_position camera_p; /*unsigned int *PlayerIndexForController[ARRAY_SIZE(((game_input *)0)->Controllers];*/ - unsigned int PlayerIndexForController[5]; - unsigned int EntityCount; - struct entity Entities[256]; + unsigned int player_index_for_controller[5]; + unsigned int entity_count; + struct entity entities[256]; - struct loaded_bitmap Backdrop; + struct loaded_bitmap backdrop; - struct hero_bitmaps HeroBitmaps[4]; + struct hero_bitmaps hero_bitmaps[4]; struct v2 rect_pos; }; diff --git a/handmade_intrinsics.h b/handmade_intrinsics.h index ee14cb7..0954f1a 100644 --- a/handmade_intrinsics.h +++ b/handmade_intrinsics.h @@ -7,77 +7,79 @@ #include #include /* memset */ -float AbsoluteValue(float Real32) +float absolute_value(float real32) { - float Result = fabs(Real32); - return Result; + float result = fabs(real32); + return result; } -int RoundFloatToInt(float Real32) +int round_float_to_int(float real32) { - int Result = (int)roundf(Real32); - return Result; + int result = (int)roundf(real32); + return result; } -int FloorFloatToInt(float Real32) +int floor_float_to_int(float real32) { - int Result = (int)floorf(Real32); - return Result; + int result = (int)floorf(real32); + return result; } -float Sin(float Angle) +float hm_sin(float angle) { - float Result = sinf(Angle); - return Result; + float result = sinf(angle); + return result; } -float Cos(float Angle) +float hm_cos(float angle) { - float Result = cosf(Angle); - return Result; + float result = cosf(angle); + return result; } -float ATan2(float Y, float X) +float hm_atan2(float y, float x) { - float Result = atan2f(Y, X); - return Result; + float result = atan2f(y, x); + return result; } struct bit_scan_result { - int Found; - unsigned int Index; + int found; + unsigned int index; }; -static struct bit_scan_result FindLeastSignificantSetBit(unsigned int Value) +static struct bit_scan_result +find_least_significant_set_bit(unsigned int value) { - struct bit_scan_result Result; - memset(&Result, 0, sizeof(Result)); + /* TODO: */ + struct bit_scan_result result; + memset(&result, 0, sizeof(result)); #if COMPILER_MSVC - unsigned long Index; - Result.Found = _BitScanForward(&Index, Value); - Result.Index = (unsigned int)Index; + unsigned long index; + result.Found = _BitScanForward(&index, value); + result.index = (unsigned int)index; #elif COMPILER_CLANG - Result.Index = __builtin_ffsll(Value); /* NOTE: It is a GCC function, + result.index = __builtin_ffsll(value); /* NOTE: It is a GCC function, but is supported by clang compiler. https://gcc.gnu.org/onlinedocs/gcc/Bit-Operation-Builtins.html*/ - if(Result.Index) { - Result.Found = 1; - if(Result.Index > 0) - Result.Index--; + if(result.index) { + result.found = 1; + if(result.index > 0) + result.index--; } #else for(unsigned int Test = 0; Test < 32; Test++) { - if(Value & (1 << Test)) { - Result.Index = Test; - Result.Found = 1; + if(value & (1 << Test)) { + result.index = Test; + result.Found = 1; break; } } #endif - return Result; + return result; } #endif diff --git a/handmade_math.h b/handmade_math.h index 58a10b5..4f83daf 100644 --- a/handmade_math.h +++ b/handmade_math.h @@ -3,79 +3,79 @@ /* TODO: Make these static. */ struct v2 { - float X, Y; - float E[2]; + float x, y; + float e[2]; }; -struct v2 V2(float X, float Y) +struct v2 V2(float x, float y) { - struct v2 Result; + struct v2 result; - Result.X = X; - Result.Y = Y; + result.x = x; + result.y = y; - return Result; + return result; } -struct v2 V2Multiply(float A, struct v2 B) +struct v2 V2Multiply(float a, struct v2 b) { - struct v2 Result; + struct v2 result; - Result.X = A * B.X; - Result.Y = A * B.Y; + result.x = a * b.x; + result.y = a * b.y; - return Result; + return result; } -struct v2 V2Unary(struct v2 A) +struct v2 V2Unary(struct v2 a) { - struct v2 Result; + struct v2 result; - Result.X = -A.X; - Result.Y = -A.Y; + result.x = -a.x; + result.y = -a.y; - return Result; + return result; } -struct v2 V2Add(struct v2 A, struct v2 B) +struct v2 V2Add(struct v2 a, struct v2 b) { - struct v2 Result; + struct v2 result; - Result.X = A.X + B.X; - Result.Y = A.Y + B.Y; + result.x = a.x + b.x; + result.y = a.y + b.y; - return Result; + return result; } -struct v2 V2Subtract(struct v2 A, struct v2 B) +struct v2 V2Subtract(struct v2 a, struct v2 b) { - struct v2 Result; + struct v2 result; - Result.X = A.X - B.X; - Result.Y = A.Y - B.Y; + result.x = a.x - b.x; + result.y = a.y - b.y; - return Result; + return result; } -float Square(float A) +float Square(float a) { - float Result; + float result; - Result = A * A; + result = a * a; - return Result; + return result; } -float InnerProduct(struct v2 A, struct v2 B) +float InnerProduct(struct v2 a, struct v2 b) { - float Result = A.X*B.X + A.Y*B.Y; - return Result; + float result = a.x*b.x + a.y*b.y; + return result; } -float LengthSq(struct v2 A) +float LengthSq(struct v2 a) { - float Result = InnerProduct(A, A); - return Result; + float result = InnerProduct(a, a); + return result; } #endif diff --git a/handmade_random.h b/handmade_random.h index 70f9f3a..2348c33 100644 --- a/handmade_random.h +++ b/handmade_random.h @@ -1,7 +1,7 @@ #ifndef HANDMADE_RANDOM_H_SENTRY #define HANDMADE_RANDOM_H_SENTRY -static unsigned int RandomNumberTable[] = { +static unsigned int random_number_table[] = { 0x215cd69f, 0x33960616, 0x200b7d2b, 0x1f908c2d, 0x264590df, 0x0a3cfc19, 0x2fd85a9a, 0x19bd3968, 0x1a36d278, 0x3552bed4, 0x1cf24f52, 0x388993cc, 0x028fb3ea, 0x2c777ded, 0x39ca8471, 0x1badf924, 0x0f95267e, 0x2a4ff029, 0x2c1b26ea, 0x0212c345, 0x304d7fe0, 0x3b4e6efe, 0x11124fce, 0x2352fc4c, diff --git a/handmade_tile.c b/handmade_tile.c index 1e98a50..ca9f75f 100644 --- a/handmade_tile.c +++ b/handmade_tile.c @@ -1,232 +1,250 @@ #include "handmade_tile.h" -static struct tile_chunk * -GetTileChunk(struct tile_map *TileMap, - unsigned int TileChunkX, unsigned int TileChunkY, - unsigned int TileChunkZ) -{ - struct tile_chunk *TileChunk = NULL; +#include - if((TileChunkX >= 0) && (TileChunkX < TileMap->TileChunkCountX) && - (TileChunkY >= 0) && (TileChunkY < TileMap->TileChunkCountY) && - (TileChunkZ >= 0) && (TileChunkZ < TileMap->TileChunkCountZ)) +static struct tile_chunk * +get_tile_chunk(struct tile_map *tile_map, + unsigned int tile_chunk_x, unsigned int tile_chunk_y, + unsigned int tile_chunk_z) +{ + struct tile_chunk *tile_chunk = NULL; + + if((tile_chunk_x >= 0) && (tile_chunk_x < tile_map->tile_chunk_count_x) && + (tile_chunk_y >= 0) && (tile_chunk_y < tile_map->tile_chunk_count_y) && + (tile_chunk_z >= 0) && (tile_chunk_z < tile_map->tile_chunk_count_z)) { - TileChunk = - &TileMap->TileChunks[(TileChunkZ * TileMap->TileChunkCountY * - TileMap->TileChunkCountX) + - (TileChunkY*TileMap->TileChunkCountX) + TileChunkX]; + tile_chunk = + &tile_map->tile_chunks[(tile_chunk_z * tile_map->tile_chunk_count_y * + tile_map->tile_chunk_count_x) + + (tile_chunk_y*tile_map->tile_chunk_count_x) + tile_chunk_x]; } - return TileChunk; + return tile_chunk; } static struct tile_chunk_position -GetChunkPositionFor(struct tile_map *TileMap, - unsigned int AbsTileX, unsigned int AbsTileY, - unsigned int AbsTileZ) +get_chunk_position_for(struct tile_map *tile_map, + unsigned int abs_tile_x, unsigned int abs_tile_y, + unsigned int abs_tile_z) { - struct tile_chunk_position Result; + struct tile_chunk_position result; - Result.TileChunkX = AbsTileX >> TileMap->ChunkShift; - Result.TileChunkY = AbsTileY >> TileMap->ChunkShift; - Result.TileChunkZ = AbsTileZ; - Result.RelTileX = AbsTileX & TileMap->ChunkMask; - Result.RelTileY = AbsTileY & TileMap->ChunkMask; + result.tile_chunk_x = abs_tile_x >> tile_map->chunk_shift; + result.tile_chunk_y = abs_tile_y >> tile_map->chunk_shift; + result.tile_chunk_z = abs_tile_z; + result.rel_tile_x = abs_tile_x & tile_map->chunk_mask; + result.rel_tile_y = abs_tile_y & tile_map->chunk_mask; - return Result; + return result; } static unsigned int -GetTileValueUnchecked(struct tile_map *TileMap, - struct tile_chunk *TileChunk, - unsigned int TileX, unsigned int TileY) +get_tile_value_unchecked(struct tile_map *tile_map, + struct tile_chunk *tile_chunk, + unsigned int tile_x, unsigned int tile_y) { - unsigned int TileChunkValue; + unsigned int tile_chunk_value; - ASSERT(TileChunk); - ASSERT(TileX < TileMap->ChunkDim); - ASSERT(TileY < TileMap->ChunkDim); + assert(tile_chunk); + assert(tile_x < tile_map->chunk_dim); + assert(tile_y < tile_map->chunk_dim); - TileChunkValue = TileChunk->Tiles[TileY * TileMap->ChunkDim + TileX]; - return TileChunkValue; + tile_chunk_value = + tile_chunk->tiles[tile_y * tile_map->chunk_dim + tile_x]; + return tile_chunk_value; } static unsigned int -GetTileChunkValue(struct tile_map *TileMap, struct tile_chunk *TileChunk, - unsigned int TestTileX, unsigned int TestTileY) +get_tile_chunk_value(struct tile_map *tile_map, + struct tile_chunk *tile_chunk, + unsigned int test_tile_x, unsigned int test_tile_y) { - unsigned int TileChunkValue = 0; + unsigned int tile_chunk_value = 0; - if(TileChunk && TileChunk->Tiles) { - TileChunkValue = - GetTileValueUnchecked(TileMap, TileChunk, TestTileX, TestTileY); + if(tile_chunk && tile_chunk->tiles) { + tile_chunk_value = + get_tile_value_unchecked(tile_map, tile_chunk, + test_tile_x, test_tile_y); } - return TileChunkValue; + return tile_chunk_value; } static unsigned int -GetTileValue(struct tile_map *TileMap, - unsigned int AbsTileX, unsigned int AbsTileY, - unsigned int AbsTileZ) +get_tile_value(struct tile_map *tile_map, + unsigned int abs_tile_x, unsigned int abs_tile_y, + unsigned int abs_tile_z) { - struct tile_chunk_position ChunkPos = - GetChunkPositionFor(TileMap, AbsTileX, AbsTileY, AbsTileZ); - struct tile_chunk *TileChunk = - GetTileChunk(TileMap, ChunkPos.TileChunkX, ChunkPos.TileChunkY, - ChunkPos.TileChunkZ); - unsigned int TileChunkValue = - GetTileChunkValue(TileMap, TileChunk, ChunkPos.RelTileX, - ChunkPos.RelTileY); - return TileChunkValue; + struct tile_chunk_position chunk_pos = + get_chunk_position_for(tile_map, abs_tile_x, abs_tile_y, abs_tile_z); + struct tile_chunk *tile_chunk = + get_tile_chunk(tile_map, chunk_pos.tile_chunk_x, chunk_pos.tile_chunk_y, + chunk_pos.tile_chunk_z); + unsigned int tile_chunk_value = + get_tile_chunk_value(tile_map, tile_chunk, chunk_pos.rel_tile_x, + chunk_pos.rel_tile_y); + return tile_chunk_value; } -static int IsTileValueEmpty(unsigned int TileValue) +static int is_tile_value_empty(unsigned int tile_value) { - int Empty = ((TileValue == 1) || (TileValue == 3) || (TileValue == 4)); - return Empty; + int empty = ((tile_value == 1) || (tile_value == 3) || (tile_value == 4)); + return empty; } -static unsigned int GetTileValueByPos(struct tile_map *TileMap, - struct tile_map_position Pos) +static unsigned int get_tile_value_by_pos(struct tile_map *tile_map, + struct tile_map_position pos) { - unsigned int TileChunkValue = - GetTileValue(TileMap, Pos.AbsTileX, Pos.AbsTileY, Pos.AbsTileZ); - return TileChunkValue; + unsigned int tile_chunk_value = + get_tile_value(tile_map, pos.abs_tile_x, + pos.abs_tile_y, pos.abs_tile_z); + return tile_chunk_value; } -static void SetTileValueUnchecked(struct tile_map *TileMap, - struct tile_chunk *TileChunk, - unsigned int TileX, unsigned int TileY, - unsigned int TileValue) +static void set_tile_value_unchecked(struct tile_map *tile_map, + struct tile_chunk *tile_chunk, + unsigned int tile_x, + unsigned int tile_y, + unsigned int tile_value) { - ASSERT(TileChunk); - ASSERT(TileX < TileMap->ChunkDim); - ASSERT(TileY < TileMap->ChunkDim); + assert(tile_chunk); + assert(tile_x < tile_map->chunk_dim); + assert(tile_y < tile_map->chunk_dim); - TileChunk->Tiles[TileY * TileMap->ChunkDim + TileX] = TileValue; + tile_chunk->tiles[tile_y * tile_map->chunk_dim + tile_x] = tile_value; } -static void SetTileChunkValue(struct tile_map *TileMap, - struct tile_chunk *TileChunk, - unsigned int TestTileX, unsigned int TestTileY, - unsigned int TileValue) +static void set_tile_chunk_value(struct tile_map *tile_map, + struct tile_chunk *tile_chunk, + unsigned int test_tile_x, + unsigned int test_tile_y, + unsigned int tile_value) { - if(TileChunk && TileChunk->Tiles) { - SetTileValueUnchecked(TileMap, TileChunk, TestTileX, TestTileY, - TileValue); + if(tile_chunk && tile_chunk->tiles) { + set_tile_value_unchecked(tile_map, tile_chunk, + test_tile_x, test_tile_y, + tile_value); } } -static int IsTileMapPointEmpty(struct tile_map *TileMap, - struct tile_map_position Pos) +static int is_tile_map_point_empty(struct tile_map *tile_map, + struct tile_map_position pos) { - unsigned int TileChunkValue = GetTileValueByPos(TileMap, Pos); - int Empty = IsTileValueEmpty(TileChunkValue); - return Empty; + unsigned int tile_chunk_value; + int empty; + + tile_chunk_value = get_tile_value_by_pos(tile_map, pos); + empty = is_tile_value_empty(tile_chunk_value); + return empty; } -static void SetTileValue(struct memory_arena *Arena, - struct tile_map *TileMap, - unsigned int AbsTileX, unsigned int AbsTileY, - unsigned int AbsTileZ, unsigned int TileValue) +static void set_tile_value(struct memory_arena *arena, + struct tile_map *tile_map, + unsigned int abs_tile_x, unsigned int abs_tile_y, + unsigned int abs_tile_z, unsigned int tile_value) { + struct tile_chunk_position chunk_pos; + struct tile_chunk *tile_chunk; - struct tile_chunk_position ChunkPos = - GetChunkPositionFor(TileMap, AbsTileX, AbsTileY, AbsTileZ); - struct tile_chunk *TileChunk = - GetTileChunk(TileMap, ChunkPos.TileChunkX, ChunkPos.TileChunkY, - ChunkPos.TileChunkZ); + chunk_pos = get_chunk_position_for(tile_map, + abs_tile_x, abs_tile_y, abs_tile_z); + tile_chunk = get_tile_chunk(tile_map, + chunk_pos.tile_chunk_x, + chunk_pos.tile_chunk_y, + chunk_pos.tile_chunk_z); - ASSERT(TileChunk); - if(!TileChunk->Tiles) { - unsigned int TileCount = TileMap->ChunkDim*TileMap->ChunkDim; - unsigned int TileIndex; + assert(tile_chunk); + if(!tile_chunk->tiles) { + unsigned int tile_count, tile_index; - TileChunk->Tiles = PUSH_ARRAY(Arena, TileCount, unsigned int); - for(TileIndex = 0; - TileIndex < TileCount; - TileIndex++) + tile_count = tile_map->chunk_dim*tile_map->chunk_dim; + + tile_chunk->tiles = PUSH_ARRAY(arena, tile_count, unsigned int); + for(tile_index = 0; + tile_index < tile_count; + tile_index++) { - TileChunk->Tiles[TileIndex] = 1; + tile_chunk->tiles[tile_index] = 1; } } - SetTileChunkValue(TileMap, TileChunk, ChunkPos.RelTileX, - ChunkPos.RelTileY, TileValue); + set_tile_chunk_value(tile_map, tile_chunk, chunk_pos.rel_tile_x, + chunk_pos.rel_tile_y, tile_value); } /* TODO: Do these belong more in a "positioning" or "geometry" file? */ -static void CannonicalizeCoord(struct tile_map *TileMap, unsigned int *Tile, - float *TileRel) +static void cannonicalize_coord(struct tile_map *tile_map, + unsigned int *tile, + float *tile_rel) { /* NOTE: The world is assumed to be toroidal topology. If you step off * one end, you come back on the other.*/ - int Offset = RoundFloatToInt(*TileRel / TileMap->TileSideInMeters); - *Tile += Offset; - *TileRel -= (float)Offset * TileMap->TileSideInMeters; + int offset = + round_float_to_int(*tile_rel / tile_map->tile_side_in_meters); + *tile += offset; + *tile_rel -= (float)offset * tile_map->tile_side_in_meters; - ASSERT(*TileRel >= -0.5f*TileMap->TileSideInMeters); - ASSERT(*TileRel <= 0.5f*TileMap->TileSideInMeters); + assert(*tile_rel >= -0.5f*tile_map->tile_side_in_meters); + assert(*tile_rel <= 0.5f*tile_map->tile_side_in_meters); } static struct tile_map_position -RecannonicalizePosition(struct tile_map *TileMap, - struct tile_map_position Pos) +recannonicalize_position(struct tile_map *tile_map, + struct tile_map_position pos) { - struct tile_map_position Result = Pos; + struct tile_map_position result = pos; - CannonicalizeCoord(TileMap, &Result.AbsTileX, &Result.Offset.X); - CannonicalizeCoord(TileMap, &Result.AbsTileY, &Result.Offset.Y); + cannonicalize_coord(tile_map, &result.abs_tile_x, &result.offset.x); + cannonicalize_coord(tile_map, &result.abs_tile_y, &result.offset.y); - return Result; + return result; } -static int AreOnSameTile(struct tile_map_position *A, - struct tile_map_position *B) +static int are_on_same_tile(struct tile_map_position *a, + struct tile_map_position *b) { - int Result = ((A->AbsTileX == B->AbsTileX) && - (A->AbsTileY == B->AbsTileY) && - (A->AbsTileZ == B->AbsTileZ)); - return Result; + int result = ((a->abs_tile_x == b->abs_tile_x) && + (a->abs_tile_y == b->abs_tile_y) && + (a->abs_tile_z == b->abs_tile_z)); + return result; } static struct tile_map_difference -SubtractInFloat(struct tile_map *TileMap, - struct tile_map_position *A, struct tile_map_position *B) +subtract_in_float(struct tile_map *tile_map, + struct tile_map_position *a, struct tile_map_position *b) { - struct tile_map_difference Result; + struct tile_map_difference result; - struct v2 dTileXY; + struct v2 d_tile_xy; - float dTileZ; + float d_tile_z; - dTileXY.X = (float)A->AbsTileX - (float)B->AbsTileX; - dTileXY.Y = (float)A->AbsTileY - (float)B->AbsTileY; + d_tile_xy.x = (float)a->abs_tile_x - (float)b->abs_tile_x; + d_tile_xy.y = (float)a->abs_tile_y - (float)b->abs_tile_y; - dTileZ = (float)A->AbsTileZ - (float)B->AbsTileZ; + d_tile_z = (float)a->abs_tile_z - (float)b->abs_tile_z; - Result.dXY = V2Add(V2Multiply(TileMap->TileSideInMeters, - dTileXY), - V2Subtract(A->Offset, B->Offset)); + result.d_xy = V2Add(V2Multiply(tile_map->tile_side_in_meters, + d_tile_xy), + V2Subtract(a->offset, b->offset)); /* TODO: Incomplete . . . */ - Result.dZ = TileMap->TileSideInMeters*dTileZ; + result.d_z = tile_map->tile_side_in_meters*d_tile_z; - return Result; + return result; } static struct tile_map_position -CenteredTilePoint(unsigned int AbsTileX, unsigned int AbsTileY, - unsigned int AbsTileZ) +centered_tile_point(unsigned int abs_tile_x, unsigned int abs_tile_y, + unsigned int abs_tile_z) { - struct tile_map_position Result; - memset(&Result, 0, sizeof(Result)); + struct tile_map_position result; + memset(&result, 0, sizeof(result)); - Result.AbsTileX = AbsTileX; - Result.AbsTileY = AbsTileY; - Result.AbsTileZ = AbsTileZ; + result.abs_tile_x = abs_tile_x; + result.abs_tile_y = abs_tile_y; + result.abs_tile_z = abs_tile_z; - return Result; + return result; } diff --git a/handmade_tile.h b/handmade_tile.h index f76d464..c8cab13 100644 --- a/handmade_tile.h +++ b/handmade_tile.h @@ -4,45 +4,45 @@ #include "handmade_math.h" struct tile_map_difference { - struct v2 dXY; - float dZ; + struct v2 d_xy; + float d_z; }; struct tile_map_position { - unsigned int AbsTileX; - unsigned int AbsTileY; - unsigned int AbsTileZ; + unsigned int abs_tile_x; + unsigned int abs_tile_y; + unsigned int abs_tile_z; /* NOTE: X and Y relative to tile center. */ - struct v2 Offset; + struct v2 offset; }; struct tile_chunk_position { - unsigned int TileChunkX; - unsigned int TileChunkY; - unsigned int TileChunkZ; + unsigned int tile_chunk_x; + unsigned int tile_chunk_y; + unsigned int tile_chunk_z; - unsigned int RelTileX; - unsigned int RelTileY; + unsigned int rel_tile_x; + unsigned int rel_tile_y; }; struct tile_chunk { - unsigned int *Tiles; + unsigned int *tiles; }; struct tile_map { - unsigned int ChunkShift; - unsigned int ChunkMask; - unsigned int ChunkDim; + unsigned int chunk_shift; + unsigned int chunk_mask; + unsigned int chunk_dim; - float TileSideInMeters; + float tile_side_in_meters; /* TODO: Real sparseness. */ - unsigned int TileChunkCountX; - unsigned int TileChunkCountY; - unsigned int TileChunkCountZ; + unsigned int tile_chunk_count_x; + unsigned int tile_chunk_count_y; + unsigned int tile_chunk_count_z; - struct tile_chunk *TileChunks; + struct tile_chunk *tile_chunks; }; #endif diff --git a/helpers.h b/helpers.h new file mode 100644 index 0000000..6535624 --- /dev/null +++ b/helpers.h @@ -0,0 +1,13 @@ +#ifndef HELPERS_SENTRY +#define HELPERS_SENTRY + +#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0])) + +#define KB(n) (((unsigned long long)(n)) << 10) +#define MB(n) (((unsigned long long)(n)) << 20) +#define GB(n) (((unsigned long long)(n)) << 30) +#define TB(n) (((unsigned long long)(n)) << 40) + +#define SWAP(T, a, b) do { T t__ = a; a = b; b = t__; } while(0) + +#endif diff --git a/libs/include/SDL3/SDL.h b/libs/include/SDL3/SDL.h new file mode 100644 index 0000000..c23f706 --- /dev/null +++ b/libs/include/SDL3/SDL.h @@ -0,0 +1,91 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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.4.12 + * + * 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 +#include + +#endif /* SDL_h_ */ diff --git a/libs/include/SDL3/SDL_assert.h b/libs/include/SDL3/SDL_assert.h new file mode 100644 index 0000000..6560d19 --- /dev/null +++ b/libs/include/SDL3/SDL_assert.h @@ -0,0 +1,700 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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(__MINGW32__) + #include + #define SDL_TriggerBreakpoint() __debugbreak() +#elif defined(_MSC_VER) && defined(_M_IX86) + #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } +#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(__TINYC__) || defined(__slimcc__)) && (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 constant that contains 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(SDL_FUNCTION) +#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 +#endif + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current file being compiled. + * + * This macro is only defined if it isn't already defined, so to override it + * (perhaps with something that doesn't provide path information at all, so + * build machine information doesn't leak into public binaries), apps can + * define this macro before including SDL.h or SDL_assert.h. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FILE __FILE_NAME__ + +#elif !defined(SDL_FILE) +#ifdef __FILE_NAME__ +#define SDL_FILE __FILE_NAME__ +#else +#define SDL_FILE __FILE__ +#endif +#endif + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current file being compiled, for use in + * assertions. + * + * This macro is only defined if it isn't already defined, so to override it + * (perhaps with something that doesn't provide path information at all, so + * build machine information doesn't leak into public binaries), apps can + * define this macro before including SDL_assert.h. For example, defining this + * to `""` will make sure no source path information is included in asserts. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_ASSERT_FILE SDL_FILE + +#elif !defined(SDL_ASSERT_FILE) +#define SDL_ASSERT_FILE SDL_FILE +#endif + + +/** + * 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) && !defined(__clang__) /* 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 = { false, 0, #condition, NULL, 0, NULL, NULL }; \ + const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_ASSERT_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/libs/include/SDL3/SDL_asyncio.h b/libs/include/SDL3/SDL_asyncio.h new file mode 100644 index 0000000..3c894d6 --- /dev/null +++ b/libs/include/SDL3/SDL_asyncio.h @@ -0,0 +1,550 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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/libs/include/SDL3/SDL_atomic.h b/libs/include/SDL3/SDL_atomic.h new file mode 100644 index 0000000..f1a8e06 --- /dev/null +++ b/libs/include/SDL3/SDL_atomic.h @@ -0,0 +1,692 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 SDL_HAS_BUILTIN(__atomic_signal_fence) || (defined(__GNUC__) && (__GNUC__ >= 5)) +#define SDL_CompilerBarrier() __atomic_signal_fence(__ATOMIC_SEQ_CST) +#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 +/* We don't unlock here to avoid possible infinite recursion */ +#define SDL_CompilerBarrier() \ +{ SDL_SpinLock _tmp = 0; SDL_LockSpinlock(&_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 SDL_HAS_BUILTIN(__atomic_thread_fence) || (defined(__GNUC__) && (__GNUC__ >= 5)) +#define SDL_MemoryBarrierRelease() __atomic_thread_fence(__ATOMIC_RELEASE) +#define SDL_MemoryBarrierAcquire() __atomic_thread_fence(__ATOMIC_ACQUIRE) +#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 ishld" : : : "memory") +#elif defined(_MSC_VER) && (defined(_M_ARM64) || defined(_M_ARM64EC)) +#include +#define SDL_MemoryBarrierRelease() __dmb(_ARM64_BARRIER_ISH) +#define SDL_MemoryBarrierAcquire() __dmb(_ARM64_BARRIER_ISHLD) +#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); + +/** + * 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_AtomicU32 variable to be modified. + * \param v the desired value to add or subtract. + * \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.4.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_AddAtomicU32(SDL_AtomicU32 *a, int v); + +/** + * 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/libs/include/SDL3/SDL_audio.h b/libs/include/SDL3/SDL_audio.h new file mode 100644 index 0000000..1e1af26 --- /dev/null +++ b/libs/include/SDL3/SDL_audio.h @@ -0,0 +1,2370 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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; the + * stream will buffer data as needed. + * - 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. + * + * **WARNING**: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK + * and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default + * physical devices' names. However, as the default device may change at any + * time, it is likely better to show a generic name to the user, like "System + * default audio device" or perhaps "default [currently %s]". Do not store + * this name to disk to reidentify the device in a later run of the program, + * as the default might change in general, and the string will be the name of + * a specific device and not the abstract system default. + * + * \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(). If the other + * end of the stream's format has never been set (the audio stream was created + * with a NULL audio spec), this function will set it to match the device + * end's format. + * + * \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. + * + * Note that `src_spec` or `dst_spec` may be NULL, but any attempts to + * put or get data from an audio stream will fail until it has valid + * specs assigned to both ends of the stream. Specs can be assigned later + * through SDL_SetAudioStreamFormat(), or binding the stream to an audio + * device (which will set the format of only the input or output, + * depending on what kind of device the stream was bound to). + * + * \param src_spec the format details of the input audio. May be NULL. + * \param dst_spec the format details of the output audio. May be NULL. + * \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. + * + * The application can hang any data it wants here, but the following + * properties are understood by SDL: + * + * - `SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN`: if true (the default), the + * stream be automatically cleaned up when the audio subsystem quits. If set + * to false, the streams will persist beyond that. This property is ignored + * for streams created through SDL_OpenAudioDeviceStream(), and will always + * be cleaned up. Streams that are not cleaned up will still be unbound from + * devices when the audio subsystem quits. This property was added in SDL + * 3.4.0. + * + * \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); + +#define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN "SDL.audiostream.auto_cleanup" + + +/** + * 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. + * + * `src_spec` and `dst_spec` may each be NULL; a NULL spec signals not to + * change the current format for that side of the stream. + * + * \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.0f will play the audio faster, and at a + * higher pitch. A value less than 1.0f will play the audio slower, and at a + * lower pitch. 1.0f means play at normal speed. + * + * This is applied during SDL_GetAudioStreamData, and can be continuously + * changed to create various effects. + * + * \param stream the stream on which 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 + * different thread at the same time, though! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamOutputChannelMap + */ +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 is 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); + +/** + * A callback that fires for completed SDL_PutAudioStreamDataNoCopy() data. + * + * When using SDL_PutAudioStreamDataNoCopy() to provide data to an + * SDL_AudioStream, it's not safe to dispose of the data until the stream has + * completely consumed it. Often times it's difficult to know exactly when + * this has happened. + * + * This callback fires once when the stream no longer needs the buffer, + * allowing the app to easily free or reuse it. + * + * \param userdata an opaque pointer provided by the app for their personal + * use. + * \param buf the pointer provided to SDL_PutAudioStreamDataNoCopy(). + * \param buflen the size of buffer, in bytes, provided to + * SDL_PutAudioStreamDataNoCopy(). + * + * \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.4.0. + * + * \sa SDL_SetAudioStreamGetCallback + * \sa SDL_SetAudioStreamPutCallback + */ +typedef void (SDLCALL *SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen); + +/** + * Add external data to an audio stream without copying it. + * + * Unlike SDL_PutAudioStreamData(), this function does not make a copy of the + * provided data, instead storing the provided pointer. This means that the + * put operation does not need to allocate and copy the data, but the original + * data must remain available until the stream is done with it, either by + * being read from the stream in its entirety, or a call to + * SDL_ClearAudioStream() or SDL_DestroyAudioStream(). + * + * The 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. + * + * An optional callback may be provided, which is called when the stream no + * longer needs the data. Once this callback fires, the stream will not access + * the data again. This callback will fire for any reason the data is no + * longer needed, including clearing or destroying the stream. + * + * Note that there is still an allocation to store tracking information, so + * this function is more efficient for larger blocks of data. If you're + * planning to put a few samples at a time, it will be more efficient to use + * SDL_PutAudioStreamData(), which allocates and buffers in blocks. + * + * \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 add to the stream. + * \param callback the callback function to call when the data is no longer + * needed by the stream. May be NULL. + * \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. + * + * \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.4.0. + * + * \sa SDL_ClearAudioStream + * \sa SDL_FlushAudioStream + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamQueued + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata); + +/** + * Add data to the stream with each channel in a separate array. + * + * 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. + * + * The data will be interleaved and queued. Note that SDL_AudioStream only + * operates on interleaved data, so this is simply a convenience function for + * easily queueing data from sources that provide separate arrays. There is no + * equivalent function to retrieve planar data. + * + * The arrays in `channel_buffers` are ordered as they are to be interleaved; + * the first array will be the first sample in the interleaved data. Any + * individual array may be NULL; in this case, silence will be interleaved for + * that channel. + * + * `num_channels` specifies how many arrays are in `channel_buffers`. This can + * be used as a safety to prevent overflow, in case the stream format has + * changed elsewhere. If more channels are specified than the current input + * spec, they are ignored. If less channels are specified, the missing arrays + * are treated as if they are NULL (silence is written to those channels). If + * the count is -1, SDL will assume the array count matches the current input + * spec. + * + * Note that `num_samples` is the number of _samples per array_. This can also + * be thought of as the number of _sample frames_ to be queued. A value of 1 + * with stereo arrays will queue two samples to the stream. This is different + * than SDL_PutAudioStreamData, which wants the size of a single array in + * bytes. + * + * \param stream the stream the audio data is being added to. + * \param channel_buffers a pointer to an array of arrays, one array per + * channel. + * \param num_channels the number of arrays in `channel_buffers` or -1. + * \param num_samples the number of _samples_ per array 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.4.0. + * + * \sa SDL_ClearAudioStream + * \sa SDL_FlushAudioStream + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamQueued + */ +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples); + +/** + * 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. + * + * SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this + * function call is required for audio playback to begin on such devices. + * + * \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. + * + * Do not call SDL_DestroyAudioStream() on `stream` during this callback. + * + * \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(). + * + * 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/libs/include/SDL3/SDL_begin_code.h b/libs/include/SDL3/SDL_begin_code.h new file mode 100644 index 0000000..4f3fe2d --- /dev/null +++ b/libs/include/SDL3/SDL_begin_code.h @@ -0,0 +1,553 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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.4.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) + +/** + * A macro to specify data alignment. + * + * This informs the compiler that a given datatype or variable must be aligned + * to a specific byte count. + * + * For example: + * + * ```c + * // make sure this is struct is aligned to 16 bytes for SIMD access. + * typedef struct { + * float x, y, z, w; + * } SDL_ALIGNED(16) MySIMDAlignedData; + * + * // make sure this one field in a struct is aligned to 16 bytes for SIMD access. + * typedef struct { + * SomeStuff stuff; + * float SDL_ALIGNED(16) position[4]; + * SomeOtherStuff other_stuff; + * } MyStruct; + * + * // make sure this variable is aligned to 32 bytes. + * int SDL_ALIGNED(32) myval = 0; + * ``` + * + * Alignment is only guaranteed for things the compiler places: local + * variables on the stack and global/static variables. To dynamically allocate + * something that respects this alignment, use SDL_aligned_alloc() or some + * other mechanism. + * + * On compilers without alignment support, this macro is defined to an invalid + * symbol, to make it clear that the current compiler is likely to generate + * incorrect code when it sees this macro. + * + * \param x the byte count to align to, so the data's address will be a + * multiple of this value. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_ALIGNED(x) __attribute__((aligned(x))) + +/* end of wiki documentation section. */ +#endif + +/* `restrict` is from C99, but __restrict works with both Visual Studio and GCC. */ +#ifndef SDL_RESTRICT +# if defined(restrict) || ((defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L))) +# define SDL_RESTRICT restrict +# elif defined(_MSC_VER) || defined(__GNUC__) || defined(__clang__) +# define SDL_RESTRICT __restrict +# else +# define SDL_RESTRICT +# endif +#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 +#if defined(_MSC_VER) && (_MSC_VER >= 1200) +#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 */ + +#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 /* __MACH__ */ + +#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 */ + +#ifndef SDL_ALIGNED +#if defined(__clang__) || defined(__GNUC__) +#define SDL_ALIGNED(x) __attribute__((aligned(x))) +#elif defined(_MSC_VER) +#define SDL_ALIGNED(x) __declspec(align(x)) +#elif defined(__cplusplus) && (__cplusplus >= 201103L) +#define SDL_ALIGNED(x) alignas(x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_ALIGNED(x) _Alignas(x) +#else +#define SDL_ALIGNED(x) PLEASE_DEFINE_SDL_ALIGNED +#endif +#endif /* SDL_ALIGNED not defined */ + diff --git a/sdl/include/SDL_bits.h b/libs/include/SDL3/SDL_bits.h similarity index 60% rename from sdl/include/SDL_bits.h rename to libs/include/SDL3/SDL_bits.h index 0894dd1..d3310ab 100644 --- a/sdl/include/SDL_bits.h +++ b/libs/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,23 @@ 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. * - * \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. + * 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. + * + * \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 +77,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 +111,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/sdl/include/SDL_blendmode.h b/libs/include/SDL3/SDL_blendmode.h similarity index 72% rename from sdl/include/SDL_blendmode.h rename to libs/include/SDL3/SDL_blendmode.h index 1f74fd8..84cf622 100644 --- a/sdl/include/SDL_blendmode.h +++ b/libs/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/libs/include/SDL3/SDL_camera.h b/libs/include/SDL3/SDL_camera.h new file mode 100644 index 0000000..14ea647 --- /dev/null +++ b/libs/include/SDL3/SDL_camera.h @@ -0,0 +1,535 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 denominator ((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; + +/** + * The current state of a request for camera access. + * + * \since This enum is available since SDL 3.4.0. + * + * \sa SDL_GetCameraPermissionState + */ +typedef enum SDL_CameraPermissionState +{ + SDL_CAMERA_PERMISSION_STATE_DENIED = -1, + SDL_CAMERA_PERMISSION_STATE_PENDING, + SDL_CAMERA_PERMISSION_STATE_APPROVED, +} SDL_CameraPermissionState; + + +/** + * 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 SDL_CAMERA_PERMISSION_STATE_PENDING if waiting for user response, + * SDL_CAMERA_PERMISSION_STATE_APPROVED if the camera is approved for use, and + * SDL_CAMERA_PERMISSION_STATE_DENIED 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 an SDL_CameraPermissionState value indicating if access is + * granted, or `SDL_CAMERA_PERMISSION_STATE_PENDING` if the decision + * is still pending. + * + * \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 SDL_CameraPermissionState 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/libs/include/SDL3/SDL_clipboard.h b/libs/include/SDL3/SDL_clipboard.h new file mode 100644 index 0000000..487f974 --- /dev/null +++ b/libs/include/SDL3/SDL_clipboard.h @@ -0,0 +1,331 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 function returns an empty string if there is 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 function returns an empty string if there is 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 the 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 the length to 0 will cause zero length data to be sent + * to the "receiver", which should be able to handle this. 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 + * when new data is set. + * + * \param userdata a pointer to the 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. SDL copies + * the given list. + * \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 *const *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 the 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. + * \returns true if data exists in the 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/sdl/include/close_code.h b/libs/include/SDL3/SDL_close_code.h similarity index 79% rename from sdl/include/close_code.h rename to libs/include/SDL3/SDL_close_code.h index c730185..ad9daa6 100644 --- a/sdl/include/close_code.h +++ b/libs/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/sdl/include/SDL_copying.h b/libs/include/SDL3/SDL_copying.h similarity index 95% rename from sdl/include/SDL_copying.h rename to libs/include/SDL3/SDL_copying.h index 48228f5..dd9dbc7 100644 --- a/sdl/include/SDL_copying.h +++ b/libs/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/libs/include/SDL3/SDL_cpuinfo.h b/libs/include/SDL3/SDL_cpuinfo.h new file mode 100644 index 0000000..5669c23 --- /dev/null +++ b/libs/include/SDL3/SDL_cpuinfo.h @@ -0,0 +1,374 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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); + +/** + * Report the size of a page of memory. + * + * Different platforms might have different memory page sizes. In current + * times, 4 kilobytes is not unusual, but newer systems are moving to larger + * page sizes, and esoteric platforms might have any unexpected size. + * + * Note that this function can return 0, which means SDL can't determine the + * page size on this platform. It will _not_ set an error string to be + * retrieved with SDL_GetError() in this case! In this case, defaulting to + * 4096 is often a reasonable option. + * + * \returns the size of a single page of memory, in bytes, or 0 if SDL can't + * determine this information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetSystemPageSize(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_cpuinfo_h_ */ diff --git a/libs/include/SDL3/SDL_dialog.h b/libs/include/SDL3/SDL_dialog.h new file mode 100644 index 0000000..1e01347 --- /dev/null +++ b/libs/include/SDL3/SDL_dialog.h @@ -0,0 +1,343 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. See the + * [`SDL_DialogFileFilter`](SDL_DialogFileFilter#code-examples) + * documentation for examples]. 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/libs/include/SDL3/SDL_dlopennote.h b/libs/include/SDL3/SDL_dlopennote.h new file mode 100644 index 0000000..299435a --- /dev/null +++ b/libs/include/SDL3/SDL_dlopennote.h @@ -0,0 +1,234 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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: DlopenNotes */ + +/** + * # CategoryDlopenNotes + * + * This header allows you to annotate your code so external tools know about + * dynamic shared library dependencies. + * + * If you determine that your toolchain doesn't support dlopen notes, you can + * disable this feature by defining `SDL_DISABLE_DLOPEN_NOTES`. You can use + * this CMake snippet to check for support: + * + * ```cmake + * include(CheckCSourceCompiles) + * find_package(SDL3 REQUIRED CONFIG COMPONENTS Headers) + * list(APPEND CMAKE_REQUIRED_LIBRARIES SDL3::Headers) + * check_c_source_compiles([==[ + * #include + * SDL_ELF_NOTE_DLOPEN("sdl-video", + * "Support for video through SDL", + * SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED, + * "libSDL-1.2.so.0", "libSDL-2.0.so.0", "libSDL3.so.0" + * ) + * int main(int argc, char *argv[]) { + * return argc + argv[0][1]; + * } + * ]==] COMPILER_SUPPORTS_SDL_ELF_NOTE_DLOPEN) + * if(NOT COMPILER_SUPPORTS_SDL_ELF_NOTE_DLOPEN) + * add_compile_definitions(-DSDL_DISABLE_DLOPEN_NOTE) + * endif() + * ``` + */ + +#ifndef SDL_dlopennote_h +#define SDL_dlopennote_h + +/** + * Use this macro with SDL_ELF_NOTE_DLOPEN() to note that a dynamic shared + * library dependency is optional. + * + * Optional functionality uses the dependency, the binary will work and the + * dependency is only needed for full-featured installations. + * + * \since This macro is available since SDL 3.4.0. + * + * \sa SDL_ELF_NOTE_DLOPEN + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED + */ +#define SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED "suggested" + +/** + * Use this macro with SDL_ELF_NOTE_DLOPEN() to note that a dynamic shared + * library dependency is recommended. + * + * Important functionality needs the dependency, the binary will work but in + * most cases the dependency should be provided. + * + * \since This macro is available since SDL 3.4.0. + * + * \sa SDL_ELF_NOTE_DLOPEN + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED + */ +#define SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended" + +/** + * Use this macro with SDL_ELF_NOTE_DLOPEN() to note that a dynamic shared + * library dependency is required. + * + * Core functionality needs the dependency, the binary will not work if it + * cannot be found. + * + * \since This macro is available since SDL 3.4.0. + * + * \sa SDL_ELF_NOTE_DLOPEN + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED + */ +#define SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED "required" + + +#if !defined(SDL_PLATFORM_UNIX) || defined(SDL_PLATFORM_ANDROID) +/* The dlopen note functionality isn't used on this platform */ +#ifndef SDL_DISABLE_DLOPEN_NOTES +#define SDL_DISABLE_DLOPEN_NOTES +#endif +#elif defined(__GNUC__) && (__GNUC__ < 3 || (__GNUC__ == 3 && __GNUC_MINOR__ < 1)) +/* gcc < 3.1 too old */ +#ifndef SDL_DISABLE_DLOPEN_NOTES +#define SDL_DISABLE_DLOPEN_NOTES +#endif +#endif /* SDL_PLATFORM_UNIX || SDL_PLATFORM_ANDROID */ + +#if defined(__ELF__) && !defined(SDL_DISABLE_DLOPEN_NOTES) + +#include + +#define SDL_ELF_NOTE_DLOPEN_VENDOR "FDO" +#define SDL_ELF_NOTE_DLOPEN_TYPE 0x407c0c0aU + +#define SDL_ELF_NOTE_INTERNAL2(json, variable_name) \ + __attribute__((aligned(4), used, section(".note.dlopen"))) \ + static const struct { \ + struct { \ + Uint32 n_namesz; \ + Uint32 n_descsz; \ + Uint32 n_type; \ + } nhdr; \ + char name[4]; \ + __attribute__((aligned(4))) char dlopen_json[sizeof(json)]; \ + } variable_name = { \ + { \ + sizeof(SDL_ELF_NOTE_DLOPEN_VENDOR), \ + sizeof(json), \ + SDL_ELF_NOTE_DLOPEN_TYPE \ + }, \ + SDL_ELF_NOTE_DLOPEN_VENDOR, \ + json \ + } + +#define SDL_ELF_NOTE_INTERNAL(json, variable_name) \ + SDL_ELF_NOTE_INTERNAL2(json, variable_name) + +#define SDL_DLNOTE_JSON_ARRAY1(N1) "[\"" N1 "\"]" +#define SDL_DLNOTE_JSON_ARRAY2(N1,N2) "[\"" N1 "\",\"" N2 "\"]" +#define SDL_DLNOTE_JSON_ARRAY3(N1,N2,N3) "[\"" N1 "\",\"" N2 "\",\"" N3 "\"]" +#define SDL_DLNOTE_JSON_ARRAY4(N1,N2,N3,N4) "[\"" N1 "\",\"" N2 "\",\"" N3 "\",\"" N4 "\"]" +#define SDL_DLNOTE_JSON_ARRAY5(N1,N2,N3,N4,N5) "[\"" N1 "\",\"" N2 "\",\"" N3 "\",\"" N4 "\",\"" N5 "\"]" +#define SDL_DLNOTE_JSON_ARRAY6(N1,N2,N3,N4,N5,N6) "[\"" N1 "\",\"" N2 "\",\"" N3 "\",\"" N4 "\",\"" N5 "\",\"" N6 "\"]" +#define SDL_DLNOTE_JSON_ARRAY7(N1,N2,N3,N4,N5,N6,N7) "[\"" N1 "\",\"" N2 "\",\"" N3 "\",\"" N4 "\",\"" N5 "\",\"" N6 "\",\"" N7 "\"]" +#define SDL_DLNOTE_JSON_ARRAY8(N1,N2,N3,N4,N5,N6,N7,N8) "[\"" N1 "\",\"" N2 "\",\"" N3 "\",\"" N4 "\",\"" N5 "\",\"" N6 "\",\"" N7 "\",\"" N8 "\"]" +#define SDL_DLNOTE_JSON_ARRAY_GET(N1,N2,N3,N4,N5,N6,N7,N8,NAME,...) NAME +#define SDL_DLNOTE_JSON_ARRAY(...) \ + SDL_DLNOTE_JSON_ARRAY_GET( \ + __VA_ARGS__, \ + SDL_DLNOTE_JSON_ARRAY8, \ + SDL_DLNOTE_JSON_ARRAY7, \ + SDL_DLNOTE_JSON_ARRAY6, \ + SDL_DLNOTE_JSON_ARRAY5, \ + SDL_DLNOTE_JSON_ARRAY4, \ + SDL_DLNOTE_JSON_ARRAY3, \ + SDL_DLNOTE_JSON_ARRAY2, \ + SDL_DLNOTE_JSON_ARRAY1 \ + )(__VA_ARGS__) + +/* Create "unique" variable name using __LINE__, + * so creating multiple elf notes on the same line is not supported + */ +#define SDL_DLNOTE_JOIN2(A,B) A##B +#define SDL_DLNOTE_JOIN(A,B) SDL_DLNOTE_JOIN2(A,B) +#define SDL_DLNOTE_UNIQUE_NAME SDL_DLNOTE_JOIN(s_SDL_dlopen_note_, __LINE__) + +/** + * Add a note that your application has dynamic shared library dependencies. + * + * You can do this by adding the following to the global scope: + * + * ```c + * SDL_ELF_NOTE_DLOPEN( + * "png", + * "Support for loading PNG images using libpng (required for APNG)", + * SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, + * "libpng12.so.0" + * ) + * ``` + * + * A trailing semicolon is not needed. + * + * Or if you support multiple versions of a library, you can list them: + * + * ```c + * // Our app supports SDL1, SDL2, and SDL3 by dynamically loading them + * SDL_ELF_NOTE_DLOPEN( + * "SDL", + * "Create windows through SDL video backend", + * SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED + * "libSDL-1.2.so.0", "libSDL2-2.0.so.0", "libSDL3.so.0" + * ) + * ``` + * + * This macro is not available for compilers that do not support variadic + * macro's. + * + * \since This macro is available since SDL 3.4.0. + * + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED + * \sa SDL_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED + */ +#define SDL_ELF_NOTE_DLOPEN(feature, description, priority, ...) \ + SDL_ELF_NOTE_INTERNAL( \ + "[{\"feature\":\"" feature \ + "\",\"description\":\"" description \ + "\",\"priority\":\"" priority \ + "\",\"soname\":" SDL_DLNOTE_JSON_ARRAY(__VA_ARGS__) "}]", \ + SDL_DLNOTE_UNIQUE_NAME); + +#elif defined(__GNUC__) && __GNUC__ < 3 + +#define SDL_ELF_NOTE_DLOPEN(args...) + +#elif defined(_MSC_VER) && _MSC_VER < 1400 + +/* Variadic macros are not supported */ + +#else + +#define SDL_ELF_NOTE_DLOPEN(...) + +#endif + +#endif /* SDL_dlopennote_h */ diff --git a/sdl/include/SDL_egl.h b/libs/include/SDL3/SDL_egl.h similarity index 99% rename from sdl/include/SDL_egl.h rename to libs/include/SDL3/SDL_egl.h index 34bd974..1371c4d 100644 --- a/sdl/include/SDL_egl.h +++ b/libs/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/libs/include/SDL3/SDL_endian.h b/libs/include/SDL3/SDL_endian.h new file mode 100644 index 0000000..69f097e --- /dev/null +++ b/libs/include/SDL3/SDL_endian.h @@ -0,0 +1,645 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. */ +#if defined(__clang__) && !SDL_HAS_BUILTIN(_m_prefetch) +#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) || defined(__GLIBC__) +#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 /* SDL_WIKI_DOCUMENTATION_SECTION */ +#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": "=abcd"(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/libs/include/SDL3/SDL_error.h b/libs/include/SDL3/SDL_error.h new file mode 100644 index 0000000..3453818 --- /dev/null +++ b/libs/include/SDL3/SDL_error.h @@ -0,0 +1,226 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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/libs/include/SDL3/SDL_events.h b/libs/include/SDL3/SDL_events.h new file mode 100644 index 0000000..312623e --- /dev/null +++ b/libs/include/SDL3/SDL_events.h @@ -0,0 +1,1645 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 occurred 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_USABLE_BOUNDS_CHANGED, /**< Display has changed usable bounds */ + SDL_EVENT_DISPLAY_FIRST = SDL_EVENT_DISPLAY_ORIENTATION, + SDL_EVENT_DISPLAY_LAST = SDL_EVENT_DISPLAY_USABLE_BOUNDS_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. + data1 is 1 for live-resize expose events, 0 otherwise. */ + 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 */ + SDL_EVENT_SCREEN_KEYBOARD_SHOWN, /**< The on-screen keyboard has been shown */ + SDL_EVENT_SCREEN_KEYBOARD_HIDDEN, /**< The on-screen keyboard has been hidden */ + + /* 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, + + /* Pinch events */ + SDL_EVENT_PINCH_BEGIN = 0x710, /**< Pinch gesture started */ + SDL_EVENT_PINCH_UPDATE, /**< Pinch gesture updated */ + SDL_EVENT_PINCH_END, /**< Pinch gesture ended */ + + /* 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 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_EVENT_DISPLAY_* */ + 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, SDL_PEN_MOUSEID for pen 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.*) + * + * Note that SDL will send a SDL_EVENT_AUDIO_DEVICE_ADDED event for every + * device it discovers during initialization. After that, this event will only + * arrive when a device is hotplugged during the program's run. + * + * \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; + +/** + * Pinch event structure (event.pinch.*) + */ +typedef struct SDL_PinchFingerEvent +{ + SDL_EventType type; /**< ::SDL_EVENT_PINCH_BEGIN or ::SDL_EVENT_PINCH_UPDATE or ::SDL_EVENT_PINCH_END */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + float scale; /**< The scale change since the last SDL_EVENT_PINCH_UPDATE. Scale < 1 is "zoom out". Scale > 1 is "zoom in". */ + SDL_WindowID windowID; /**< The window underneath the finger, if any */ +} SDL_PinchFingerEvent; + +/** + * Pressure-sensitive pen proximity event structure (event.pproximity.*) + * + * 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. + * + * Not all platforms have a window associated with the pen during proximity + * events. Some wait until motion/button/etc events to offer this info. + * + * \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, 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_PinchFingerEvent pinch; /**< Pinch 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_static_cast(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`. + * + * If `event` is NULL, it simply returns true 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 initialized the video subsystem. + * + * 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 + * } + * ``` + * + * Note that Windows (and possibly other platforms) has a quirk about how it + * handles events while dragging/resizing a window, which can cause this + * function to block for significant amounts of time. Technical explanations + * and solutions are discussed on the wiki: + * + * https://wiki.libsdl.org/SDL3/AppFreezeDuringDrag + * + * \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! The exception is handling of + * SDL_EVENT_WINDOW_EXPOSED, which is guaranteed to be sent from the OS on the + * main thread and you are expected to redraw your window in response to this + * event. + * + * 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 a 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); + +/** + * Generate an English description of an event. + * + * This will fill `buf` with a null-terminated string that might look + * something like this: + * + * ``` + * SDL_EVENT_MOUSE_MOTION (timestamp=1140256324 windowid=2 which=0 state=0 x=492.99 y=139.09 xrel=52 yrel=6) + * ``` + * + * The exact format of the string is not guaranteed; it is intended for + * logging purposes, to be read by a human, and not parsed by a computer. + * + * The returned value follows the same rules as SDL_snprintf(): `buf` will + * always be NULL-terminated (unless `buflen` is zero), and will be truncated + * if `buflen` is too small. The return code is the number of bytes needed for + * the complete string, not counting the NULL-terminator, whether the string + * was truncated or not. Unlike SDL_snprintf(), though, this function never + * returns -1. + * + * \param event an event to describe. May be NULL. + * \param buf the buffer to fill with the description string. May be NULL. + * \param buflen the maximum bytes that can be written to `buf`. + * \returns number of bytes needed for the full string, not counting the + * null-terminator byte. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetEventDescription(const SDL_Event *event, char *buf, int buflen); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_events_h_ */ diff --git a/libs/include/SDL3/SDL_filesystem.h b/libs/include/SDL3/SDL_filesystem.h new file mode 100644 index 0000000..3a077a0 --- /dev/null +++ b/libs/include/SDL3/SDL_filesystem.h @@ -0,0 +1,537 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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/` + * + * **Android Specific Functionality**: This function returns "./", which + * allows filesystem operations to use internal storage and the asset system. + * + * **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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * Due to historical mistakes, `org` is allowed to be NULL or "". In such + * cases, SDL will omit the org subdirectory, including on platforms where it + * shouldn't, and including on platforms where this would make your app fail + * certification for an app store. New apps should definitely specify a real + * string for `org`. + * + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_GetUserFolder(SDL_Folder folder); + + +/* Abstract filesystem interface */ + +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, 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. + * + * \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_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. + * + * \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_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. + * + * \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_RemovePath(const char *path); + +/** + * Rename a file or directory. + * + * If the file at `newpath` already exists, it will be 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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread, but this + * operation is not atomic, so the app might need to protect + * access to specific paths from other threads if appropriate. + * + * \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. + * + * Symlinks, on filesystems that support them, are always followed, so you + * will always get information on what the symlink eventually points to, and + * not the symlink itself. + * + * \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. + * + * \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_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. + * + * \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_GetCurrentDirectory(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_filesystem_h_ */ diff --git a/libs/include/SDL3/SDL_gamepad.h b/libs/include/SDL3/SDL_gamepad.h new file mode 100644 index 0000000..9c88a77 --- /dev/null +++ b/libs/include/SDL3/SDL_gamepad.h @@ -0,0 +1,1656 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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're using SDL gamepad support in a Steam game, you must call + * SteamAPI_InitEx() before calling SDL_Init(). + * + * 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_GAMECUBE, + 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 GameCube controllers this + * would be A/X/B/Y, 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, Steam Controller QAM 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, DualSense Edge RB button, Right Joy-Con SR button, Steam Controller R4 button) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3, DualSense Edge LB button, Left Joy-Con SL button, Steam Controller L4 button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2, DualSense Edge right Fn button, Right Joy-Con SL button, Steam Controller R5 button) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4, DualSense Edge left Fn button, Left Joy-Con SR button, Steam Controller L5 button) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button (e.g. Nintendo GameCube left trigger click) */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button (e.g. Nintendo GameCube right trigger click) */ + 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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * Note that for invalid gamepads or axes, this will return 0. Zero is also a + * valid value in normal operation; usually it means a centered axis. + * + * \param gamepad a gamepad. + * \param axis an axis index (one of the SDL_GamepadAxis values). + * \returns axis state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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 button. + * \returns the SDL_GamepadButton enum corresponding to the input string, or + * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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 the remarks in SDL_SensorType for 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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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/libs/include/SDL3/SDL_gpu.h b/libs/include/SDL3/SDL_gpu.h new file mode 100644 index 0000000..dfe5994 --- /dev/null +++ b/libs/include/SDL3/SDL_gpu.h @@ -0,0 +1,4606 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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](https://renderdoc.org/) + * can be very helpful for diagnosing incorrect behavior and performance + * issues. + * + * ## System Requirements + * + * ### Vulkan + * + * SDL driver name: "vulkan" (for use in SDL_CreateGPUDevice() and + * SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING) + * + * 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` + * - `sampleRateShading` + * + * You can remove some of these requirements to increase compatibility with + * Android devices by using these properties when creating the GPU device with + * SDL_CreateGPUDeviceWithProperties(): + * + * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN + * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN + * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN + * - SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN + * + * ### D3D12 + * + * SDL driver name: "direct3d12" + * + * 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_0 and + * Resource Binding Tier 2 or above. + * + * You can remove the Tier 2 resource binding requirement to support Intel + * Haswell and Broadwell GPUs by using this property when creating the GPU + * device with SDL_CreateGPUDeviceWithProperties(): + * + * - SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN + * + * ### Metal + * + * SDL driver name: "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 + * + * ## Coordinate System + * + * The GPU API uses a left-handed coordinate system, following the convention + * of D3D12 and Metal. Specifically: + * + * - **Normalized Device Coordinates:** The lower-left corner has an x,y + * coordinate of `(-1.0, -1.0)`. The upper-right corner is `(1.0, 1.0)`. Z + * values range from `[0.0, 1.0]` where 0 is the near plane. + * - **Viewport Coordinates:** The top-left corner has an x,y coordinate of + * `(0, 0)` and extends to the bottom-right corner at `(viewportWidth, + * viewportHeight)`. +Y is down. + * - **Texture Coordinates:** The top-left corner has an x,y coordinate of + * `(0, 0)` and extends to the bottom-right corner at `(1.0, 1.0)`. +Y is + * down. + * + * If the backend driver differs from this convention (e.g. Vulkan, which has + * an NDC that assumes +Y is down), SDL will automatically convert the + * coordinate system behind the scenes, so you don't need to perform any + * coordinate flipping logic in your shaders. + * + * ## 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. + * + * ## Debugging + * + * At some point of your GPU journey, you will probably encounter issues that + * are not traceable with regular debugger - for example, your code compiles + * but you get an empty screen, or your shader fails in runtime. + * + * For debugging such cases, there are tools that allow visually inspecting + * the whole GPU frame, every drawcall, every bound resource, memory buffers, + * etc. They are the following, per platform: + * + * * For Windows/Linux, use + * [RenderDoc](https://renderdoc.org/) + * * For MacOS (Metal), use Xcode built-in debugger (Open XCode, go to Debug > + * Debug Executable..., select your application, set "GPU Frame Capture" to + * "Metal" in scheme "Options" window, run your app, and click the small + * Metal icon on the bottom to capture a frame) + * + * Aside from that, you may want to enable additional debug layers to receive + * more detailed error messages, based on your GPU backend: + * + * * For D3D12, the debug layer is an optional feature that can be installed + * via "Windows Settings -> System -> Optional features" and adding the + * "Graphics Tools" optional feature. + * * For Vulkan, you will need to install Vulkan SDK on Windows, and on Linux, + * you usually have some sort of `vulkan-validation-layers` system package + * that should be installed. + * * For Metal, it should be enough just to run the application from XCode to + * receive detailed errors or warnings in the output. + * + * Don't hesitate to use tools as RenderDoc when encountering runtime issues + * or unexpected output on screen, quick GPU frame inspection can usually help + * you fix the majority of such problems. + */ + +#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 evaluates 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. + * + * If either of `pixels_per_row` or `rows_per_layer` is zero, then width and + * height of passed SDL_GPUTextureRegion to SDL_UploadToGPUTexture or + * SDL_DownloadFromGPUTexture are used as default values respectively and data + * is considered to be tightly packed. + * + * **WARNING**: On some older/integrated hardware, Direct3D 12 requires + * texture data row pitch to be 256 byte aligned, and offsets to be aligned to + * 512 bytes. If they are not, SDL will make a temporary copy of the data that + * is properly aligned, but this adds overhead to the transfer process. Apps + * can avoid this by aligning their data appropriately, or using a different + * GPU backend than Direct3D 12. + * + * \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 size of a single element + the offset between elements. */ + 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 + * \sa SDL_GPUBlendFactor + * \sa SDL_GPUBlendOp + * \sa SDL_GPUColorComponentFlags + */ +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 + * \sa SDL_GPUShaderFormat + * \sa SDL_GPUShaderStage + */ +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. */ + bool enable_alpha_to_coverage; /**< true enables the alpha-to-coverage feature. */ + 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 + * \sa SDL_FColor + */ +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. + * + * Due to ABI limitations, depth textures with more than 255 layers are not + * supported. + * + * \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 mip_level; /**< The mip level to use as the depth stencil target. */ + Uint8 layer; /**< The layer index to use as the depth stencil target. */ +} 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 + * \sa SDL_GPUTexture + * \sa SDL_GPUSampler + */ +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. + * + * The GPU driver name can be one of the following: + * + * - "vulkan": [Vulkan](CategoryGPU#vulkan) + * - "direct3d12": [D3D12](CategoryGPU#d3d12) + * - "metal": [Metal](CategoryGPU#metal) + * - NULL: let SDL pick the optimal driver + * + * \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_CreateGPUDeviceWithProperties + * \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_VERBOSE_BOOLEAN`: enable to automatically log + * useful debug information on device creation, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to + * use, if a specific one is desired. + * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN`: Enable Vulkan + * device feature shaderClipDistance. If disabled, clip distances are not + * supported in shader code: gl_ClipDistance[] built-ins of GLSL, + * SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of + * Metal. Disabling optional features allows the application to run on some + * older Android devices. Defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN`: Enable + * Vulkan device feature depthClamp. If disabled, there is no depth clamp + * support and enable_depth_clip in SDL_GPURasterizerState must always be + * set to true. Disabling optional features allows the application to run on + * some older Android devices. Defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN`: + * Enable Vulkan device feature drawIndirectFirstInstance. If disabled, the + * argument first_instance of SDL_GPUIndirectDrawCommand must be set to + * zero. Disabling optional features allows the application to run on some + * older Android devices. Defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN`: Enable Vulkan + * device feature samplerAnisotropy. If disabled, enable_anisotropy of + * SDL_GPUSamplerCreateInfo must be set to false. Disabling optional + * features allows the application to run on some older Android devices. + * Defaults to true. + * + * 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 backend: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to + * use for all vertex semantics, default is "TEXCOORD". + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN`: By + * default, Resourcing Binding Tier 2 is required for D3D12 support. + * However, an application can set this property to true to enable Tier 1 + * support, if (and only if) the application uses 8 or fewer storage + * resources across all shader stages. As of writing, this property is + * useful for targeting Intel Haswell and Broadwell GPUs; other hardware + * either supports Tier 2 Resource Binding or does not support D3D12 in any + * capacity. Defaults to false. + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_VERSION_NUMBER`: Certain + * feature checks are only possible on Windows 11 by default. By setting + * this alongside `SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_PATH_STRING` + * and vendoring D3D12Core.dll from the D3D12 Agility SDK, you can make + * those feature checks possible on older platforms. The version you provide + * must match the one given in the DLL. + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_PATH_STRING`: Certain + * feature checks are only possible on Windows 11 by default. By setting + * this alongside + * `SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_VERSION_NUMBER` and + * vendoring D3D12Core.dll from the D3D12 Agility SDK, you can make those + * feature checks possible on older platforms. The path you provide must be + * relative to the executable path of your app. Be sure not to put the DLL + * in the same directory as the exe; Microsoft strongly advises against + * this! + * + * With the Vulkan backend: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN`: + * By default, Vulkan device enumeration includes drivers of all types, + * including software renderers (for example, the Lavapipe Mesa driver). + * This can be useful if your application _requires_ SDL_GPU, but if you can + * provide your own fallback renderer (for example, an OpenGL renderer) this + * property can be set to true. Defaults to false. + * - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER`: a pointer to an + * SDL_GPUVulkanOptions structure to be processed during device creation. + * This allows configuring a variety of Vulkan-specific options such as + * increasing the API version and opting into extensions aside from the + * minimal set SDL requires. + * + * With the Metal backend: - + * `SDL_PROP_GPU_DEVICE_CREATE_METAL_ALLOW_MACFAMILY1_BOOLEAN`: By default, + * macOS support requires what Apple calls "MTLGPUFamilyMac2" hardware or + * newer. However, an application can set this property to true to enable + * support for "MTLGPUFamilyMac1" hardware, if (and only if) the application + * does not write to sRGB textures. (For history's sake: MacFamily1 also does + * not support indirect command buffers, MSAA depth resolve, and stencil + * resolve/feedback, but these are not exposed features in SDL_GPU.) + * + * \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_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose" +#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" +#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN "SDL.gpu.device.create.feature.clip_distance" +#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN "SDL.gpu.device.create.feature.depth_clamping" +#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN "SDL.gpu.device.create.feature.indirect_draw_first_instance" +#define SDL_PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN "SDL.gpu.device.create.feature.anisotropy" +#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_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN "SDL.gpu.device.create.d3d12.allowtier1resourcebinding" +#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" +#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_VERSION_NUMBER "SDL.gpu.device.create.d3d12.agility_sdk_version" +#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_AGILITY_SDK_PATH_STRING "SDL.gpu.device.create.d3d12.agility_sdk_path" +#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN "SDL.gpu.device.create.vulkan.requirehardwareacceleration" +#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER "SDL.gpu.device.create.vulkan.options" +#define SDL_PROP_GPU_DEVICE_CREATE_METAL_ALLOW_MACFAMILY1_BOOLEAN "SDL.gpu.device.create.metal.allowmacfamily1" + + +/** + * A structure specifying additional options when using Vulkan. + * + * When no such structure is provided, SDL will use Vulkan API version 1.0 and + * a minimal set of features. The requested API version influences how the + * feature_list is processed by SDL. When requesting API version 1.0, the + * feature_list is ignored. Only the vulkan_10_physical_device_features and + * the extension lists are used. When requesting API version 1.1, the + * feature_list is scanned for feature structures introduced in Vulkan 1.1. + * When requesting Vulkan 1.2 or higher, the feature_list is additionally + * scanned for compound feature structs such as + * VkPhysicalDeviceVulkan11Features. The device and instance extension lists, + * as well as vulkan_10_physical_device_features, are always processed. + * + * \since This struct is available since SDL 3.4.0. + */ +typedef struct SDL_GPUVulkanOptions +{ + Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance. Use Vulkan's VK_MAKE_VERSION or VK_MAKE_API_VERSION. */ + void *feature_list; /**< Pointer to the first element of a chain of Vulkan feature structs. (Requires API version 1.1 or higher.)*/ + void *vulkan_10_physical_device_features; /**< Pointer to a VkPhysicalDeviceFeatures struct to enable additional Vulkan 1.0 features. */ + Uint32 device_extension_count; /**< Number of additional device extensions to require. */ + const char **device_extension_names; /**< Pointer to a list of additional device extensions to require. */ + Uint32 instance_extension_count; /**< Number of additional instance extensions to require. */ + const char **instance_extension_names; /**< Pointer to a list of additional instance extensions to require. */ +} SDL_GPUVulkanOptions; + +/** + * 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); + +/** + * Get the properties associated with a GPU device. + * + * All properties are optional and may differ between GPU backends and SDL + * versions. + * + * The following properties are provided by SDL: + * + * `SDL_PROP_GPU_DEVICE_NAME_STRING`: Contains the name of the underlying + * device as reported by the system driver. This string has no standardized + * format, is highly inconsistent between hardware devices and drivers, and is + * able to change at any time. Do not attempt to parse this string as it is + * bound to fail at some point in the future when system drivers are updated, + * new hardware devices are introduced, or when SDL adds new GPU backends or + * modifies existing ones. + * + * Strings that have been found in the wild include: + * + * - GTX 970 + * - GeForce GTX 970 + * - NVIDIA GeForce GTX 970 + * - Microsoft Direct3D12 (NVIDIA GeForce GTX 970) + * - NVIDIA Graphics Device + * - GeForce GPU + * - P106-100 + * - AMD 15D8:C9 + * - AMD Custom GPU 0405 + * - AMD Radeon (TM) Graphics + * - ASUS Radeon RX 470 Series + * - Intel(R) Arc(tm) A380 Graphics (DG2) + * - Virtio-GPU Venus (NVIDIA TITAN V) + * - SwiftShader Device (LLVM 16.0.0) + * - llvmpipe (LLVM 15.0.4, 256 bits) + * - Microsoft Basic Render Driver + * - unknown device + * + * The above list shows that the same device can have different formats, the + * vendor name may or may not appear in the string, the included vendor name + * may not be the vendor of the chipset on the device, some manufacturers + * include pseudo-legal marks while others don't, some devices may not use a + * marketing name in the string, the device string may be wrapped by the name + * of a translation interface, the device may be emulated in software, or the + * string may contain generic text that does not identify the device at all. + * + * `SDL_PROP_GPU_DEVICE_DRIVER_NAME_STRING`: Contains the self-reported name + * of the underlying system driver. + * + * Strings that have been found in the wild include: + * + * - Intel Corporation + * - Intel open-source Mesa driver + * - Qualcomm Technologies Inc. Adreno Vulkan Driver + * - MoltenVK + * - Mali-G715 + * - venus + * + * `SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING`: Contains the self-reported + * version of the underlying system driver. This is a relatively short version + * string in an unspecified format. If SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING + * is available then that property should be preferred over this one as it may + * contain additional information that is useful for identifying the exact + * driver version used. + * + * Strings that have been found in the wild include: + * + * - 53.0.0 + * - 0.405.2463 + * - 32.0.15.6614 + * + * `SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING`: Contains the detailed version + * information of the underlying system driver as reported by the driver. This + * is an arbitrary string with no standardized format and it may contain + * newlines. This property should be preferred over + * SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING if it is available as it usually + * contains the same information but in a format that is easier to read. + * + * Strings that have been found in the wild include: + * + * - 101.6559 + * - 1.2.11 + * - Mesa 21.2.2 (LLVM 12.0.1) + * - Mesa 22.2.0-devel (git-f226222 2022-04-14 impish-oibaf-ppa) + * - v1.r53p0-00eac0.824c4f31403fb1fbf8ee1042422c2129 + * + * This string has also been observed to be a multiline string (which has a + * trailing newline): + * + * ``` + * Driver Build: 85da404, I46ff5fc46f, 1606794520 + * Date: 11/30/20 + * Compiler Version: EV031.31.04.01 + * Driver Branch: promo490_3_Google + * ``` + * + * \param device a GPU context 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.4.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGPUDeviceProperties(SDL_GPUDevice *device); + +#define SDL_PROP_GPU_DEVICE_NAME_STRING "SDL.gpu.device.name" +#define SDL_PROP_GPU_DEVICE_DRIVER_NAME_STRING "SDL.gpu.device.driver_name" +#define SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING "SDL.gpu.device.driver_version" +#define SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING "SDL.gpu.device.driver_info" + + +/* 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, either via SDL_UploadToGPUTexture or by performing a render or + * compute pass with this texture as a target. + * + * 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_BeginGPURenderPass + * \sa SDL_BeginGPUComputePass + * \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. + * + * On Direct3D 12, using SDL_InsertGPUDebugLabel requires + * WinPixEventRuntime.dll to be in your PATH or in the same directory as your + * executable. See + * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/) + * for instructions on how to obtain it. + * + * \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 arbitrary 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 Direct3D 12, using SDL_PushGPUDebugGroup requires WinPixEventRuntime.dll + * to be in your PATH or in the same directory as your executable. See + * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/) + * for instructions on how to obtain it. + * + * 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. + * + * On Direct3D 12, using SDL_PopGPUDebugGroup requires WinPixEventRuntime.dll + * to be in your PATH or in the same directory as your executable. See + * [here](https://devblogs.microsoft.com/pix/winpixeventruntime/) + * for instructions on how to obtain it. + * + * \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 in this command buffer 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. + * + * For detailed information about accessing uniform data from a shader, please + * refer to SDL_CreateGPUShader. + * + * \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 in this command buffer 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 in this command buffer 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. + * + * Using SDL_GPU_LOADOP_LOAD before any contents have been written to the + * texture subresource will result in undefined behavior. SDL_GPU_LOADOP_CLEAR + * will set the contents of the texture subresource to a single value before + * any rendering is performed. It's fine to do an empty render pass using + * SDL_GPU_STOREOP_STORE to clear a texture, but in general it's better to + * think of clearing not as an independent operation but as something that's + * done as the beginning of a 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_CreateGPUComputePipeline(). + * + * \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_CreateGPUComputePipeline + */ +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_CreateGPUComputePipeline(). + * + * \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_CreateGPUComputePipeline + */ +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_CreateGPUComputePipeline(). + * + * \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_CreateGPUComputePipeline + */ +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. + * + * \sa SDL_EndGPUCopyPass + */ +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. + * + * This function does not support copying between depth and color textures. + * For those, copy the texture to a buffer and then to the destination + * texture. + * + * \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 is 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. This NULL pointer should not be + * passed back into SDL. Instead, it should be considered as an indication to + * wait until the swapchain is available. + * + * 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); + +/** + * Get the SDL pixel format corresponding to a GPU texture format. + * + * \param format a texture format. + * \returns the corresponding pixel format, or SDL_PIXELFORMAT_UNKNOWN if + * there is no corresponding pixel format. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatFromGPUTextureFormat(SDL_GPUTextureFormat format); + +/** + * Get the GPU texture format corresponding to an SDL pixel format. + * + * \param format a pixel format. + * \returns the corresponding GPU texture format, or + * SDL_GPU_TEXTUREFORMAT_INVALID if there is no corresponding GPU + * texture format. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUTextureFormatFromPixelFormat(SDL_PixelFormat format); + +#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/sdl/include/SDL_guid.h b/libs/include/SDL3/SDL_guid.h similarity index 70% rename from sdl/include/SDL_guid.h rename to libs/include/SDL3/SDL_guid.h index 775b4ed..cf9df31 100644 --- a/sdl/include/SDL_guid.h +++ b/libs/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. + * 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. * - * This is an acronym for "Globally Unique ID." - * - * 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/sdl/include/SDL_haptic.h b/libs/include/SDL3/SDL_haptic.h similarity index 65% rename from sdl/include/SDL_haptic.h rename to libs/include/SDL3/SDL_haptic.h index 9f14fd8..ef91904 100644 --- a/sdl/include/SDL_haptic.h +++ b/libs/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; + * SDL_HapticEffectID 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,28 @@ 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; + +/* + * Misc defines. + */ + +/** + * Used to play a device an infinite number of times. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect + */ +#define SDL_HAPTIC_INFINITY 4294967295U /** @@ -155,59 +175,73 @@ typedef struct _SDL_Haptic SDL_Haptic; */ /* @{ */ +/** + * Type of haptic effect. + */ +typedef Uint16 SDL_HapticEffectType; + /** * Constant effect supported. * * 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 +251,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 +263,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 +275,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 +287,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 +299,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 +355,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) /** @@ -315,9 +401,16 @@ typedef struct _SDL_Haptic SDL_Haptic; */ /* @{ */ +/** + * Type of coordinates used for haptic direction. + */ +typedef Uint8 SDL_HapticDirectionType; + /** * 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 +418,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 +427,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 +439,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 @@ -350,16 +449,15 @@ typedef struct _SDL_Haptic SDL_Haptic; /* @} *//* Haptic features */ -/* - * Misc defines. - */ /** - * Used to play a device an infinite number of times. + * ID for haptic effects. * - * \sa SDL_HapticRunEffect + * This is -1 if the ID is invalid. + * + * \sa SDL_CreateHapticEffect */ -#define SDL_HAPTIC_INFINITY 4294967295U +typedef int SDL_HapticEffectID; /** @@ -456,17 +554,19 @@ 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 { - Uint8 type; /**< The type of encoding. */ - Sint32 dir[3]; /**< The encoded direction. */ + SDL_HapticDirectionType type; /**< The type of encoding. */ + Sint32 dir[3]; /**< The encoded direction. */ } SDL_HapticDirection; @@ -478,13 +578,15 @@ 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 */ typedef struct SDL_HapticConstant { /* Header */ - Uint16 type; /**< SDL_HAPTIC_CONSTANT */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_CONSTANT */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -558,8 +660,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,9 +672,9 @@ typedef struct SDL_HapticConstant typedef struct SDL_HapticPeriodic { /* Header */ - Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT, - SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or - SDL_HAPTIC_SAWTOOTHDOWN */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -612,6 +716,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 @@ -622,8 +728,8 @@ typedef struct SDL_HapticPeriodic typedef struct SDL_HapticCondition { /* Header */ - Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, - SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -653,13 +759,15 @@ 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 */ typedef struct SDL_HapticRamp { /* Header */ - Uint16 type; /**< SDL_HAPTIC_RAMP */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_RAMP */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -690,13 +798,15 @@ 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 */ typedef struct SDL_HapticLeftRight { /* Header */ - Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_LEFTRIGHT */ /* Replay */ Uint32 length; /**< Duration of the effect in milliseconds. */ @@ -718,13 +828,15 @@ 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 */ typedef struct SDL_HapticCustom { /* Header */ - Uint16 type; /**< SDL_HAPTIC_CUSTOM */ + SDL_HapticEffectType type; /**< SDL_HAPTIC_CUSTOM */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -811,6 +923,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 @@ -821,7 +935,7 @@ typedef struct SDL_HapticCustom typedef union SDL_HapticEffect { /* Common for all force feedback effects */ - Uint16 type; /**< Effect type. */ + SDL_HapticEffectType type; /**< Effect type. */ SDL_HapticConstant constant; /**< Constant effect. */ SDL_HapticPeriodic periodic; /**< Periodic effect. */ SDL_HapticCondition condition; /**< Condition effect. */ @@ -830,36 +944,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 +998,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. - * - * \sa SDL_HapticOpen - * \sa SDL_HapticOpened + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic); +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_GetHapticNameForID + */ +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 +1070,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 +1104,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 +1147,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 +1163,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 +1177,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 +1204,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 SDL_HapticEffectID SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Update the properties of an effect. @@ -1095,24 +1221,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, SDL_HapticEffectID effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1127,36 +1250,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, SDL_HapticEffectID 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, SDL_HapticEffectID effect); /** * Destroy a haptic effect on the device. @@ -1167,12 +1285,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, SDL_HapticEffectID effect); /** * Get the status of the current effect on the specified haptic device. @@ -1181,16 +1298,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, SDL_HapticEffectID effect); /** * Set the global gain of the specified haptic device. @@ -1199,20 +1314,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 +1339,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 2.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect + * \sa SDL_StopHapticEffect */ -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 +1429,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/libs/include/SDL3/SDL_hidapi.h b/libs/include/SDL3/SDL_hidapi.h new file mode 100644 index 0000000..90e574c --- /dev/null +++ b/libs/include/SDL3/SDL_hidapi.h @@ -0,0 +1,571 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 + +#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); + +/** + * Get the properties associated with an SDL_hid_device. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER`: the libusb_device_handle + * associated with the device, if it was opened using libusb. + * + * \param dev a device handle returned from SDL_hid_open(). + * \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.4.0. + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_hid_get_properties(SDL_hid_device *dev); + +#define SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER "SDL.hidapi.libusb.device.handle" + +/** + * 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/libs/include/SDL3/SDL_hints.h b/libs/include/SDL3/SDL_hints.h new file mode 100644 index 0000000..cce34f3 --- /dev/null +++ b/libs/include/SDL3/SDL_hints.h @@ -0,0 +1,5000 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * For Windows WASAPI audio, the following roles are supported, and map to + * `AUDIO_STREAM_CATEGORY`: + * + * - "Other" (default) + * - "Communications" - Real-time communications, such as VOIP or chat + * - "Game" - Game audio + * - "GameChat" - Game chat audio, similar to "Communications" except that + * this will not attenuate other audio streams + * - "Movie" - Music or sound with dialog + * - "Media" - Music or sound without dialog + * + * Android's AAudio target supports this hint as of SDL 3.4.4. Android does + * not support the exact same options as WASAPI, but for portability, will + * attempt to map these same strings to the `aaudio_usage_t` constants. For + * example, "Movie" and "Media" will both map to `AAUDIO_USAGE_MEDIA`, etc. + * + * If your application applies its own echo cancellation, gain control, and + * noise reduction it should also set SDL_HINT_AUDIO_DEVICE_RAW_STREAM. + * + * 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 whether this audio device should do audio processing. + * + * Some operating systems perform echo cancellation, gain control, and noise + * reduction as needed. If your application already handles these, you can set + * this hint to prevent the OS from doing additional audio processing. + * + * This corresponds to the WASAPI audio option `AUDCLNT_STREAMOPTIONS_RAW`. + * + * The variable can be set to the following values: + * + * - "0": audio processing can be done by the OS. (default) + * - "1": audio processing is done by the application. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_AUDIO_DEVICE_RAW_STREAM "SDL_AUDIO_DEVICE_RAW_STREAM" + +/** + * 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 the enabled features to be limited 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" + +/** + * Set the level of checking for invalid parameters passed to SDL functions. + * + * The variable can be set to the following values: + * + * - "1": Enable fast parameter error checking, e.g. quick NULL checks, etc. + * - "2": Enable full parameter error checking, e.g. validating objects are + * the correct type, etc. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_INVALID_PARAM_CHECKS "SDL_INVALID_PARAM_CHECKS" + +/** + * 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. + * + * 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 + * - "#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 that controls whether the Steam on-screen keyboard should be + * shown when text input is active. + * + * Steam will set this hint via environment variable for games launched in Big + * Picture mode. To override this you should call SDL_SetHintWithPriority() + * with priority `SDL_HINT_OVERRIDE`. + * + * The variable can be set to the following values: + * + * - "0": Do not show the Steam on-screen keyboard. + * - "1": Show the Steam on-screen keyboard. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.4.12. + */ +#define SDL_HINT_ENABLE_STEAM_SCREEN_KEYBOARD "SDL_ENABLE_STEAM_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 for GameCube adapters. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will not use libusb for GameCube adapters. + * - "1": HIDAPI will use libusb for GameCube adapters if available. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_HIDAPI_LIBUSB_GAMECUBE "SDL_HIDAPI_LIBUSB_GAMECUBE" + +/** + * 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 and later + * 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 controlling whether GameInput should be used for handling + * GIP devices that require raw report processing, but aren't supported + * by HIDRAW, such as Xbox One Guitars. + * + * Note that this is only supported with GameInput 3 or newer. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used to handle raw GIP devices. + * - "1": GameInput is used. + * + * The default is "1" when using GameInput 3 or newer, and is "0" otherwise. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.4.4. + */ +#define SDL_HINT_JOYSTICK_GAMEINPUT_RAW "SDL_JOYSTICK_GAMEINPUT_RAW" + +/** + * 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. + * + * 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_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + +/** + * A variable controlling whether the HIDAPI driver for some Logitech wheels + * 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_LG4FF "SDL_JOYSTICK_HIDAPI_LG4FF" + +/** + * A variable controlling whether the HIDAPI driver for 8BitDo 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_8BITDO "SDL_JOYSTICK_HIDAPI_8BITDO" + +/** + * A variable controlling whether the HIDAPI driver for SInput controllers + * should be used. + * + * More info - https://github.com/HandHeldLegend/SInput-HID + * + * 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SINPUT "SDL_JOYSTICK_HIDAPI_SINPUT" + +/** + * A variable controlling whether the HIDAPI driver for ZUIKI 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_ZUIKI "SDL_JOYSTICK_HIDAPI_ZUIKI" + +/** + * A variable controlling whether the HIDAPI driver for Flydigi 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_FLYDIGI "SDL_JOYSTICK_HIDAPI_FLYDIGI" + +/** + * 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 the HIDAPI driver for Nintendo Switch 2 + * 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.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH2 "SDL_JOYSTICK_HIDAPI_SWITCH2" + +/** + * 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 the new HIDAPI driver for wired Xbox One + * (GIP) 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_ONE. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_GIP "SDL_JOYSTICK_HIDAPI_GIP" + +/** + * A variable controlling whether the new HIDAPI driver for wired Xbox One + * (GIP) controllers should reset the controller if it can't get the metadata + * from the controller. + * + * The variable can be set to the following values: + * + * - "0": Assume this is a generic controller. + * - "1": Reset the controller to get metadata. + * + * By default the controller is not reset. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_GIP_RESET_FOR_METADATA "SDL_JOYSTICK_HIDAPI_GIP_RESET_FOR_METADATA" + +/** + * 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. (default) + * - "1": WGI is used. + * + * 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 English + * QWERTY 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 that controls whether KMSDRM will use "atomic" functionality. + * + * The KMSDRM backend can use atomic commits, if both DRM_CLIENT_CAP_ATOMIC + * and DRM_CLIENT_CAP_UNIVERSAL_PLANES is supported by the system. As of SDL + * 3.4.0, it will favor this functionality, but in case this doesn't work well + * on a given system or other surprises, this hint can be used to disable it. + * + * This hint can not enable the functionality if it isn't available. + * + * The variable can be set to the following values: + * + * - "0": SDL will not use the KMSDRM "atomic" functionality. + * - "1": SDL will allow usage of the KMSDRM "atomic" functionality. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_KMSDRM_ATOMIC "SDL_KMSDRM_ATOMIC" + +/** + * 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` + * + * If the `DEBUG_INVOCATION` environment variable is set to "1", the default + * log levels are equivalent to: + * + * `assert=warn,test=verbose,*=debug` + * + * 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" + +/** + * A variable controlling whether holding down a key will repeat the pressed + * key or open the accents menu on macOS. + * + * The variable can be set to the following values: + * + * - "0": Holding a key will repeat the pressed key. + * - "1": Holding a key will open the accents menu for that key. (default) + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_MAC_PRESS_AND_HOLD "SDL_MAC_PRESS_AND_HOLD" + +/** + * 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 doesn't have to be an integer value. For example, "59.94" won't be + * rounded to an integer rate; the digits after the decimal are actually + * respected. + * + * 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 setting whether we should scale cursors by the current display + * scale. + * + * The variable can be set to the following values: + * + * - "0": Cursors will not change size based on the display content scale. + * (default) + * - "1": Cursors will automatically match the display content scale (e.g. a + * 2x sized cursor will be used when the window is on a monitor with 200% + * scale). This is currently implemented on Windows. + * + * This hint needs to be set before creating cursors. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_MOUSE_DPI_SCALE_CURSORS "SDL_MOUSE_DPI_SCALE_CURSORS" + +/** + * 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 traveled 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" + +/** + * A variable controlling whether to force an sRGB-capable OpenGL context. + * + * At OpenGL context creation time, some platforms can request an sRGB-capable + * context. However, sometimes any form of the request can cause surprising + * results on some drivers, platforms, and hardware. Usually the surprise is + * in the form of rendering that is either a little darker or a little + * brighter than intended. + * + * This hint allows the user to override the app's sRGB requests and either + * force a specific value, or avoid requesting anything at all, depending on + * what makes things work correctly for their system. + * + * This is meant as a fail-safe; apps should probably not explicitly set this, + * and most users should not, either. + * + * Note that some platforms cannot make this request at all, and on all + * platforms this request can be denied by the operating system. + * + * In addition to attempting to obtain the type of sRGB-capable OpenGL context + * requested by this hint, SDL will try to force the state of + * GL_FRAMEBUFFER_SRGB on the new context, if appropriate. + * + * The variable can be set to the following values: + * + * - "0": Force a request for an OpenGL context that is _not_ sRGB-capable. + * - "1": Force a request for an OpenGL context that _is_ sRGB-capable. + * - "skip": Don't make any request for an sRGB-capable context (don't specify + * the attribute at all during context creation time). + * - any other string is undefined behavior. + * + * If unset, or set to an empty string, SDL will make a request using the + * value the app specified with the SDL_GL_FRAMEBUFFER_SRGB_CAPABLE attribute. + * + * This hint should be set before an OpenGL context is created. + * + * \since This hint is available since SDL 3.4.2. + */ +#define SDL_HINT_OPENGL_FORCE_SRGB_FRAMEBUFFER "SDL_OPENGL_FORCE_SRGB_FRAMEBUFFER" + +/** + * 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 use the Direct3D 11 WARP software + * rasterizer. + * + * For more information, see: + * https://learn.microsoft.com/en-us/windows/win32/direct3darticles/directx-warp + * + * The variable can be set to the following values: + * + * - "0": Disable WARP rasterizer. (default) + * - "1": Enable WARP rasterizer. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_RENDER_DIRECT3D11_WARP "SDL_RENDER_DIRECT3D11_WARP" + +/** + * 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 the width of the PS2's framebuffer in pixels. + * + * By default, the variable is "640". + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_PS2_GS_WIDTH "SDL_PS2_GS_WIDTH" + +/** + * A variable controlling the height of the PS2's framebuffer in pixels. + * + * By default, the variable is "448". + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_PS2_GS_HEIGHT "SDL_PS2_GS_HEIGHT" + +/** + * A variable controlling whether the signal is interlaced or progressive. + * + * The variable can be set to the following values: + * + * - "0": Image is interlaced. (default) + * - "1": Image is progressive. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_PS2_GS_PROGRESSIVE "SDL_PS2_GS_PROGRESSIVE" + +/** + * A variable controlling the video mode of the console. + * + * The variable can be set to the following values: + * + * - "": Console-native. (default) + * - "NTSC": 60hz region. + * - "PAL": 50hz region. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_PS2_GS_MODE "SDL_PS2_GS_MODE" + +/** + * 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 desktops, the connector names associated with displays can be + * found in the `name` property of the info output from `wayland-info -i + * wl_output`. On X11 desktops, the `xrandr` utility can be used to retrieve + * the connector names associated with displays. + * + * 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 indicating whether the metal layer drawable size should be + * updated for the SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event on macOS. + * + * The variable can be set to the following values: + * + * - "0": the metal layer drawable size will not be updated on the + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. + * - "1": the metal layer drawable size will be updated on the + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. (default) + * + * This hint should be set before SDL_Metal_CreateView called. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_VIDEO_METAL_AUTO_RESIZE_DRAWABLE "SDL_VIDEO_METAL_AUTO_RESIZE_DRAWABLE" + +/** + * A variable controlling whether SDL will attempt to automatically set the + * destination display to a mode most closely matching that of the previous + * display if an exclusive fullscreen window is moved onto it. + * + * The variable can be set to the following values: + * + * - "0": SDL will not attempt to automatically set a matching mode on the + * destination display. If an exclusive fullscreen window is moved to a new + * display, the window will become fullscreen desktop. + * - "1": SDL will attempt to automatically set a mode on the destination + * display that most closely matches the mode of the display that the + * exclusive fullscreen window was previously on. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_VIDEO_MATCH_EXCLUSIVE_MODE_ON_MOVE "SDL_VIDEO_MATCH_EXCLUSIVE_MODE_ON_MOVE" + +/** + * 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. + * - "1": Fullscreen windows are minimized when they lose focus. + * - "auto": Fullscreen windows are minimized when they lose focus if they use + * exclusive fullscreen modes, so the desktop video mode is restored. + * (default) + * + * 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 the X Synchronization Extension is enabled. + * + * If set, this can result in smoother window resizing when rendering using + * OpenGL, however, there are some conditions: + * + * - It is only activated on windows created with the `SDL_WINDOW_OPENGL` flag + * (windows using an SDL OpenGL renderer have this automatically set). + * - When activated, presentation must be done with `SDL_GL_SwapWindow()` + * (`SDL_RenderPresent()` calls this internally for OpenGL renderers as well). + * + * Enabling this and presenting via an external mechanism will result in sync + * requests not being acked, and hangs and other odd window behavior may result. + * + * The variable can be set to the following values: + * + * - "0": The X Synchronization Extension is disabled. (default) + * - "1": The X Synchronization Extension is enabled. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.4.10. + */ +#define SDL_HINT_VIDEO_X11_ENABLE_XSYNC_EXT "SDL_VIDEO_X11_ENABLE_XSYNC_EXT" + +/** + * 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. (default) + * - "1": GameInput is used for raw keyboard and mouse events, if available. + * + * 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 or not the RIDEV_NOHOTKEYS flag is set when + * enabling Windows raw keyboard events. + * + * This blocks any hotkeys that have been registered by applications from + * having any effect beyond generating raw WM_INPUT events. + * + * This flag does not affect system-hotkeys like ALT-TAB or CTRL-ALT-DEL, but + * does affect the Windows Logo key since it is a userland hotkey registered + * by explorer.exe. + * + * The variable can be set to the following values: + * + * - "0": Hotkeys are not excluded. (default) + * - "1": Hotkeys are excluded. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.4.0. + */ +#define SDL_HINT_WINDOWS_RAW_KEYBOARD_EXCLUDE_HOTKEYS "SDL_WINDOWS_RAW_KEYBOARD_EXCLUDE_HOTKEYS" + +/** + * A variable controlling whether the RIDEV_INPUTSINK flag is set when + * enabling Windows raw keyboard events. + * + * This enables the window to still receive input even if not in foreground. + * + * Focused windows that receive text input will still prevent input events from triggering. + * + * - "0": Input is not received when not in focus or foreground. (default) + * - "1": Input will be received even when not in focus or foreground. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.4.4. + */ +#define SDL_HINT_WINDOWS_RAW_KEYBOARD_INPUTSINK "SDL_WINDOWS_RAW_KEYBOARD_INPUTSINK" + +/** + * 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. + * + * \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. In the + * initial call, the current value is in both `oldValue` and `newValue`. + * + * \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/libs/include/SDL3/SDL_init.h b/libs/include/SDL3/SDL_init.h new file mode 100644 index 0000000..d75ccc3 --- /dev/null +++ b/libs/include/SDL3/SDL_init.h @@ -0,0 +1,507 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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. + * + * \threadsafety This function is not thread safe. + * + * \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. + * + * \threadsafety This function is not thread safe. + * + * \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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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/libs/include/SDL3/SDL_intrin.h b/libs/include/SDL3/SDL_intrin.h new file mode 100644 index 0000000..a2e9680 --- /dev/null +++ b/libs/include/SDL3/SDL_intrin.h @@ -0,0 +1,410 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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)) +/* 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. */ +#if defined(__clang__) && !SDL_HAS_BUILTIN(_m_prefetch) +#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(__loongarch64) && defined(__GNUC__) && (__GNUC__ >= 15) +/* LoongArch requires GCC 15+ for target attribute support */ +# define SDL_HAS_TARGET_ATTRIBS +#elif defined(__clang__) && defined(__has_attribute) +# if __has_attribute(target) +# define SDL_HAS_TARGET_ATTRIBS +# endif +#elif defined(__GNUC__) && !defined(__loongarch64) && (__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/libs/include/SDL3/SDL_iostream.h b/libs/include/SDL3/SDL_iostream.h new file mode 100644 index 0000000..f369fde --- /dev/null +++ b/libs/include/SDL3/SDL_iostream.h @@ -0,0 +1,1379 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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`. `size` will always be > 0. + * + * 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. `size` will always be > 0. + * + * 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. + * - "wx": Create an empty file for writing. If a file with the same name + * already exists, the call fails. + * - "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. + * - "w+x": Create an empty file for both reading and writing. If a file with + * the same name already exists, the call fails. + * - "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 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_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. + * + * 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. + * + * Additionally, the following properties are recognized: + * + * - `SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER`: if this property is set to + * a non-NULL value it will be interpreted as a function of SDL_free_func + * type and called with the passed `mem` pointer when closing the stream. By + * default it is unset, i.e., the memory will not be freed. + * + * \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" +#define SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER "SDL.iostream.memory.free" + +/** + * 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. + * + * 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. + * + * Additionally, the following properties are recognized: + * + * - `SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER`: if this property is set to + * a non-NULL value it will be interpreted as a function of SDL_free_func + * type and called with the passed `mem` pointer when closing the stream. By + * default it is unset, i.e., the memory will not be freed. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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. + * + * A request for zero bytes on a valid stream will return zero immediately + * without accessing the stream, so the stream status (EOF, err, etc) will not + * change. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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. + * + * A request for zero bytes on a valid stream will return zero immediately + * without accessing the stream, so the stream status (EOF, err, etc) will not + * change. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 It is safe to call this function from any thread. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 It is safe to call this function from any thread. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 read or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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 Do not use the same SDL_IOStream from two threads at once. + * + * \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/libs/include/SDL3/SDL_joystick.h b/libs/include/SDL3/SDL_joystick.h new file mode 100644 index 0000000..c93b352 --- /dev/null +++ b/libs/include/SDL3/SDL_joystick.h @@ -0,0 +1,1385 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 + * + * SDL can provide virtual joysticks as well: the app defines an imaginary + * controller with SDL_AttachVirtualJoystick(), and then can provide inputs + * for it via SDL_SetJoystickVirtualAxis(), SDL_SetJoystickVirtualButton(), + * etc. As this data is supplied, it will look like a normal joystick to SDL, + * just not backed by a hardware driver. This has been used to make unusual + * devices, like VR headset controllers, look like normal joysticks, or + * provide recording/playback of game inputs, etc. + */ + +#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. + * + * You may refer to + * [XInput Controller Types](https://learn.microsoft.com/en-us/windows/win32/xinput/xinput-and-controller-subtypes) + * table for a general understanding of each joystick type. + * + * \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. + * + * \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_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); + +/** + * Unlocking for atomic access to the joystick API. + * + * \threadsafety This should be called from the same thread that called + * SDL_LockJoysticks(). + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * Apps can create virtual joysticks, that exist without hardware directly + * backing them, and have program-supplied inputs. Once attached, a virtual + * joystick looks like any other joystick that SDL can access. These can be + * used to make other things look like joysticks, or provide pre-recorded + * input, etc. + * + * Once attached, the app can send joystick inputs to the new virtual joystick + * using SDL_SetJoystickVirtualAxis(), etc. + * + * When no longer needed, the virtual joystick can be removed by calling + * SDL_DetachVirtualJoystick(). + * + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). + * \returns the joystick instance 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_DetachVirtualJoystick + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualTouchpad + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualTouchpad + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualTouchpad + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualTouchpad + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualTouchpad + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualSensorData + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetJoystickVirtualAxis + * \sa SDL_SetJoystickVirtualButton + * \sa SDL_SetJoystickVirtualBall + * \sa SDL_SetJoystickVirtualHat + * \sa SDL_SetJoystickVirtualTouchpad + */ +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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); + +/** + * Close a joystick previously opened with SDL_OpenJoystick(). + * + * \param joystick the joystick device to close. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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/libs/include/SDL3/SDL_keyboard.h b/libs/include/SDL3/SDL_keyboard.h new file mode 100644 index 0000000..d14ab6f --- /dev/null +++ b/libs/include/SDL3/SDL_keyboard.h @@ -0,0 +1,608 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * \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/libs/include/SDL3/SDL_keycode.h b/libs/include/SDL3/SDL_keycode.h new file mode 100644 index 0000000..1818ee3 --- /dev/null +++ b/libs/include/SDL3/SDL_keycode.h @@ -0,0 +1,347 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 + * by default 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. + * + * Many common keycodes are listed below, but this list is not exhaustive. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_HINT_KEYCODE_OPTIONS + */ +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/sdl/include/SDL_loadso.h b/libs/include/SDL3/SDL_loadso.h similarity index 59% rename from sdl/include/SDL_loadso.h rename to libs/include/SDL3/SDL_loadso.h index 9a33377..51d0d88 100644 --- a/sdl/include/SDL_loadso.h +++ b/libs/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. * - * \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_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/sdl/include/SDL_locale.h b/libs/include/SDL3/SDL_locale.h similarity index 64% rename from sdl/include/SDL_locale.h rename to libs/include/SDL3/SDL_locale.h index 6638cb3..9f03aa9 100644 --- a/sdl/include/SDL_locale.h +++ b/libs/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,22 @@ 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. + * \threadsafety This function is not thread safe. + * + * \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 +114,6 @@ extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); } /* *INDENT-ON* */ #endif -#include "close_code.h" +#include -#endif /* _SDL_locale_h */ - -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_locale_h */ diff --git a/libs/include/SDL3/SDL_log.h b/libs/include/SDL3/SDL_log.h new file mode 100644 index 0000000..f193abf --- /dev/null +++ b/libs/include/SDL3/SDL_log.h @@ -0,0 +1,541 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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: ". + * + * This function makes a copy of its string argument, **prefix**, so it is not + * necessary to keep the value of **prefix** alive after the call returns. + * + * \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_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. It should be called with NULL for + * the userdata argument. + * + * \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/libs/include/SDL3/SDL_main.h b/libs/include/SDL3/SDL_main.h new file mode 100644 index 0000000..771572f --- /dev/null +++ b/libs/include/SDL3/SDL_main.h @@ -0,0 +1,704 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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) || defined(SDL_PLATFORM_TVOS) + /* On iOS and tvOS SDL provides a main function that creates an application delegate and starts the application run loop. + + To use it, just #include 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_WIKI_DOCUMENTATION_SECTION */ + +#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. + * + * \threadsafety This function is called once by SDL, at startup, on a single + * thread. + * + * \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 + * SDL_APP_CONTINUE. 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 in all cases, even if SDL_AppInit requests + * termination at startup. + * + * 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. + * + * \threadsafety This function is not thread safe. + * + * \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(). + * + * If `argv` is NULL, SDL will provide command line arguments, either by + * querying the OS for them if possible, or supplying a filler array if not. + * + * \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. + * + * If `name` is NULL, SDL currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` for + * the style, regardless of what is specified here. + * + * \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. + * \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. + * + * \threadsafety This function is not thread safe. + * + * \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. + * + * \threadsafety This function is not thread safe. + * + * \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 should be called from an event watch in response to an + * `SDL_EVENT_DID_ENTER_BACKGROUND` event. + * + * When using SDL_Render, your event watch should be added _after_ creating + * the `SDL_Renderer`; this allows the timing of the D3D12 command queue + * suspension to execute in the correct order. + * + * When using SDL_GPU, this should be called after calling SDL_GDKSuspendGPU. + * + * If you're writing your own D3D12 renderer, this should be called after + * calling `ID3D12CommandQueue::SuspendX`. + * + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + */ +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/libs/include/SDL3/SDL_main_impl.h b/libs/include/SDL3/SDL_main_impl.h new file mode 100644 index 0000000..bf5f583 --- /dev/null +++ b/libs/include/SDL3/SDL_main_impl.h @@ -0,0 +1,151 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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/sdl/include/SDL_messagebox.h b/libs/include/SDL3/SDL_messagebox.h similarity index 60% rename from sdl/include/SDL_messagebox.h rename to libs/include/SDL3/SDL_messagebox.h index 1ba397b..af604e2 100644 --- a/sdl/include/SDL_messagebox.h +++ b/libs/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,16 @@ 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. + * \threadsafety This function should only be called on the main thread. + * + * \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 +209,22 @@ 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. + * \threadsafety This function should only be called on the main thread. + * + * \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/sdl/include/SDL_metal.h b/libs/include/SDL3/SDL_metal.h similarity index 63% rename from sdl/include/SDL_metal.h rename to libs/include/SDL3/SDL_metal.h index a3581a4..6b0e171 100644 --- a/sdl/include/SDL_metal.h +++ b/libs/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,17 @@ 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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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 +80,27 @@ 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. + * \param view the SDL_MetalView object. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ -extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); +extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); /** * 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_Metal_CreateView + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(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. - * - * \since This function is available since SDL 2.0.14. - * - * \sa SDL_GetWindowSize - * \sa SDL_CreateWindow - */ -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 +108,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/sdl/include/SDL_misc.h b/libs/include/SDL3/SDL_misc.h similarity index 82% rename from sdl/include/SDL_misc.h rename to libs/include/SDL3/SDL_misc.h index 4b9a28c..654c005 100644 --- a/sdl/include/SDL_misc.h +++ b/libs/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,21 @@ 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. + * \threadsafety This function should only be called on the main thread. + * + * \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/libs/include/SDL3/SDL_mouse.h b/libs/include/SDL3/SDL_mouse.h new file mode 100644 index 0000000..fb03c01 --- /dev/null +++ b/libs/include/SDL3/SDL_mouse.h @@ -0,0 +1,813 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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; + +/** + * Animated cursor frame info. + * + * \since This struct is available since SDL 3.4.0. + */ +typedef struct SDL_CursorFrameInfo +{ + SDL_Surface *surface; /**< The surface data for this frame */ + Uint32 duration; /**< The frame duration in milliseconds (a duration of 0 is infinite) */ +} SDL_CursorFrameInfo; + +/** + * 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) + +/** + * A callback used to transform mouse motion delta from raw values. + * + * This is called during SDL's handling of platform mouse events to scale the + * values of the resulting motion delta. + * + * \param userdata what was passed as `userdata` to + * SDL_SetRelativeMouseTransform(). + * \param timestamp the associated time at which this mouse motion event was + * received. + * \param window the associated window to which this mouse motion event was + * addressed. + * \param mouseID the associated mouse from which this mouse motion event was + * emitted. + * \param x pointer to a variable that will be treated as the resulting x-axis + * motion. + * \param y pointer to a variable that will be treated as the resulting y-axis + * motion. + * + * \threadsafety This callback is called by SDL's internal mouse input + * processing procedure, which may be a thread separate from the + * main event loop that is run at realtime priority. Stalling + * this thread with too much work in the callback can therefore + * potentially freeze the entire system. Care should be taken + * with proper synchronization practices when adding other side + * effects beyond mutation of the x and y values. + * + * \since This datatype is available since SDL 3.4.0. + * + * \sa SDL_SetRelativeMouseTransform + */ +typedef void (SDLCALL *SDL_MouseMotionTransformCallback)( + void *userdata, + Uint64 timestamp, + SDL_Window *window, + SDL_MouseID mouseID, + float *x, float *y +); + +/* 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 a user-defined function by which to transform relative mouse inputs. + * + * This overrides the relative system scale and relative speed scale hints. + * Should be called prior to enabling relative mouse mode, fails otherwise. + * + * \param callback a callback used to transform relative mouse motion, or NULL + * for default behavior. + * \param userdata a pointer that will be 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.4.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRelativeMouseTransform(SDL_MouseMotionTransformCallback callback, void *userdata); + +/** + * 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_CreateAnimatedCursor + * \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 added + * with SDL_AddSurfaceAlternateImage(), 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 if + * SDL_HINT_MOUSE_DPI_SCALE_CURSORS is enabled. 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_AddSurfaceAlternateImage + * \sa SDL_CreateAnimatedCursor + * \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 an animated color cursor. + * + * Animated cursors are composed of a sequential array of frames, specified as + * surfaces and durations in an array of SDL_CursorFrameInfo structs. The hot + * spot coordinates are universal to all frames, and all frames must have the + * same dimensions. + * + * Frame durations are specified in milliseconds. A duration of 0 implies an + * infinite frame time, and the animation will stop on that frame. To create a + * one-shot animation, set the duration of the last frame in the sequence to + * 0. + * + * If this function is passed surfaces with alternate representations added + * with SDL_AddSurfaceAlternateImage(), the surfaces 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 surfaces are 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. + * + * If the underlying platform does not support animated cursors, this function + * will fall back to creating a static color cursor using the first frame in + * the sequence. + * + * \param frames an array of cursor images composing the animation. + * \param frame_count the number of frames in the sequence. + * \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.4.0. + * + * \sa SDL_AddSurfaceAlternateImage + * \sa SDL_CreateCursor + * \sa SDL_CreateColorCursor + * \sa SDL_CreateSystemCursor + * \sa SDL_DestroyCursor + * \sa SDL_SetCursor + */ +extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateAnimatedCursor(SDL_CursorFrameInfo *frames, + int frame_count, + 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 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_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_CreateAnimatedCursor + * \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/libs/include/SDL3/SDL_mutex.h b/libs/include/SDL3/SDL_mutex.h new file mode 100644 index 0000000..29e8f1a --- /dev/null +++ b/libs/include/SDL3/SDL_mutex.h @@ -0,0 +1,1117 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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(true, 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. + * + * \threadsafety This call must be paired with a previous locking call on the + * same thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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(true, 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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(true, 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. + * + * \threadsafety This call must be paired with a previous locking call on the + * same thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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 + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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_InitState 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/libs/include/SDL3/SDL_oldnames.h b/libs/include/SDL3/SDL_oldnames.h new file mode 100644 index 0000000..cbf0453 --- /dev/null +++ b/libs/include/SDL3/SDL_oldnames.h @@ -0,0 +1,1339 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 SDL_WINDOWEVENT_deprecated_use_SDL_EVENT_WINDOW_NAME +#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_GameControllerEventState SDL_GameControllerEventState_deprecated_use_SDL_SetGamepadEventsEnabled_true_false +#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_ACCELEROMETER_AS_JOYSTICK SDL_HINT_ACCELEROMETER_AS_JOYSTICK_deprecated_use_SDL_GamepadHasSensor_and_SDL_SetGamepadSensorEnabled +#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 +#define SDL_HINT_RENDER_SCALE_QUALITY SDL_HINT_RENDER_SCALE_QUALITY_deprecated_use_SDL_SetTextureScaleMode_with_SDL_SCALEMODE_NEAREST +#define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS_deprecated_remove_this_line + +/* ##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 +#define SDL_NumJoysticks SDL_NumJoysticks_deprecated_use_SDL_GetJoysticks + +/* ##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_RENDERER_ACCELERATED SDL_RENDERER_ACCELERATED_deprecated_remove_this_line +#define SDL_RENDERER_PRESENTVSYNC SDL_RENDERER_PRESENTVSYNC_deprecated_use_SDL_SetRenderVSync +#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_SetWindowInputFocus SDL_SetWindowInputFocus_deprecated_use_SDL_RaiseWindow +#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_INIT_EVERYTHING SDL_INIT_EVERYTHING_deprecated_list_flags_explicitly +#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_FULLSCREEN_DESKTOP SDL_WINDOW_FULLSCREEN_DESKTOP_deprecated_use_SDL_SetWindowFullscreen_with_bool +#define SDL_WINDOW_INPUT_GRABBED SDL_WINDOW_INPUT_GRABBED_renamed_SDL_WINDOW_MOUSE_GRABBED +#define SDL_WINDOW_SHOWN SDL_WINDOW_SHOWN_deprecated_windows_are_shown_by_default +#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/sdl/include/SDL_opengl.h b/libs/include/SDL3/SDL_opengl.h similarity index 63% rename from sdl/include/SDL_opengl.h rename to libs/include/SDL3/SDL_opengl.h index d19c7f4..733f2b5 100644 --- a/sdl/include/SDL_opengl.h +++ b/libs/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,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +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 /* @@ -1539,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #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 ); @@ -1562,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, 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); @@ -1649,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #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 ); @@ -1757,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, 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 + @@ -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/sdl/include/SDL_opengl_glext.h b/libs/include/SDL3/SDL_opengl_glext.h similarity index 100% rename from sdl/include/SDL_opengl_glext.h rename to libs/include/SDL3/SDL_opengl_glext.h diff --git a/sdl/include/SDL_opengles.h b/libs/include/SDL3/SDL_opengles.h similarity index 94% rename from sdl/include/SDL_opengles.h rename to libs/include/SDL3/SDL_opengles.h index 2c8bc1a..227f51b 100644 --- a/sdl/include/SDL_opengles.h +++ b/libs/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/sdl/include/SDL_opengles2.h b/libs/include/SDL3/SDL_opengles2.h similarity index 86% rename from sdl/include/SDL_opengles2.h rename to libs/include/SDL3/SDL_opengles2.h index 20fcdbe..2c74614 100644 --- a/sdl/include/SDL_opengles2.h +++ b/libs/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/sdl/include/SDL_opengles2_gl2.h b/libs/include/SDL3/SDL_opengles2_gl2.h similarity index 100% rename from sdl/include/SDL_opengles2_gl2.h rename to libs/include/SDL3/SDL_opengles2_gl2.h diff --git a/sdl/include/SDL_opengles2_gl2ext.h b/libs/include/SDL3/SDL_opengles2_gl2ext.h similarity index 100% rename from sdl/include/SDL_opengles2_gl2ext.h rename to libs/include/SDL3/SDL_opengles2_gl2ext.h diff --git a/sdl/include/SDL_opengles2_gl2platform.h b/libs/include/SDL3/SDL_opengles2_gl2platform.h similarity index 100% rename from sdl/include/SDL_opengles2_gl2platform.h rename to libs/include/SDL3/SDL_opengles2_gl2platform.h diff --git a/sdl/include/SDL_opengles2_khrplatform.h b/libs/include/SDL3/SDL_opengles2_khrplatform.h similarity index 100% rename from sdl/include/SDL_opengles2_khrplatform.h rename to libs/include/SDL3/SDL_opengles2_khrplatform.h diff --git a/libs/include/SDL3/SDL_pen.h b/libs/include/SDL3/SDL_pen.h new file mode 100644 index 0000000..63f32bb --- /dev/null +++ b/libs/include/SDL3/SDL_pen.h @@ -0,0 +1,198 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 pen events: + * + * - SDL_EVENT_PEN_PROXIMITY_IN, SDL_EVENT_PEN_PROXIMITY_OUT + * (SDL_PenProximityEvent) + * - SDL_EVENT_PEN_DOWN, SDL_EVENT_PEN_UP (SDL_PenTouchEvent) + * - SDL_EVENT_PEN_MOTION (SDL_PenMotionEvent) + * - SDL_EVENT_PEN_BUTTON_DOWN, SDL_EVENT_PEN_BUTTON_UP (SDL_PenButtonEvent) + * - SDL_EVENT_PEN_AXIS (SDL_PenAxisEvent) + * + * Pens may provide more than simple touch input; they might have other axes, + * such as pressure, tilt, rotation, etc. + * + * 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. A pen leaving proximity (being taken far enough away from the + * digitizer tablet that it no longer reponds) and then coming back should + * fire proximity events, but the SDL_PenID should remain consistent. + * Unplugging the digitizer and reconnecting may cause future input to have a + * new SDL_PenID, as SDL may not know that this is the same hardware. + * + * Please note that various platforms vary wildly in how (and how well) they + * support pen input. If your pen supports some piece of functionality but SDL + * doesn't seem to, it might actually be the operating system's fault. For + * example, some platforms can manage multiple devices at the same time, but + * others will make any connected pens look like a single logical device, much + * how all USB mice connected to a computer will move the same system cursor. + * Other platforms might not support pen buttons, or the distance axis, etc. + * Very few platforms can even report _what_ functionality the pen supports in + * the first place, so best practices is to either build UI to let the user + * configure their pens, or be prepared to handle new functionality for a pen + * the first time an event is reported. + */ + +#ifndef SDL_pen_h_ +#define SDL_pen_h_ + +#include +#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's digitizer table is physically detached from the computer, it might + * get a new ID when reconnected, as SDL won't know it's the same device. + * + * These IDs are only stable within a single run of a program; the next time a + * program is run, the pen's ID will likely be different, even if the hardware + * hasn't been disconnected, etc. + * + * \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 */ +#define SDL_PEN_INPUT_IN_PROXIMITY (1u << 31) /**< pen is in proximity (since SDL 3.4.0) */ + +/** + * 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; + +/** + * An enum that describes the type of a pen device. + * + * A "direct" device is a pen that touches a graphic display (like an Apple + * Pencil on an iPad's screen). "Indirect" devices touch an external tablet + * surface that is connected to the machine but is not a display (like a + * lower-end Wacom tablet connected over USB). + * + * Apps may use this information to decide if they should draw a cursor; if + * the pen is touching the screen directly, a cursor doesn't make sense and + * can be in the way, but becomes necessary for indirect devices to know where + * on the display they are interacting. + * + * \since This enum is available since SDL 3.4.0. + */ +typedef enum SDL_PenDeviceType +{ + SDL_PEN_DEVICE_TYPE_INVALID = -1, /**< Not a valid pen device. */ + SDL_PEN_DEVICE_TYPE_UNKNOWN, /**< Don't know specifics of this pen. */ + SDL_PEN_DEVICE_TYPE_DIRECT, /**< Pen touches display. */ + SDL_PEN_DEVICE_TYPE_INDIRECT /**< Pen touches something that isn't the display. */ +} SDL_PenDeviceType; + +/** + * Get the device type of the given pen. + * + * Many platforms do not supply this information, so an app must always be + * prepared to get an SDL_PEN_DEVICE_TYPE_UNKNOWN result. + * + * \param instance_id the pen instance ID. + * \returns the device type of the given pen, or SDL_PEN_DEVICE_TYPE_INVALID + * 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.4.0. + */ +extern SDL_DECLSPEC SDL_PenDeviceType SDLCALL SDL_GetPenDeviceType(SDL_PenID instance_id); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_pen_h_ */ + diff --git a/libs/include/SDL3/SDL_pixels.h b/libs/include/SDL3/SDL_pixels.h new file mode 100644 index 0000000..475e5f9 --- /dev/null +++ b/libs/include/SDL3/SDL_pixels.h @@ -0,0 +1,1441 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 a floating point, 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_BT601_LIMITED /**< 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 pixelvalue 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 pixelvalue, 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 pixelvalue 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 pixelvalue, 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/sdl/include/SDL_test_log.h b/libs/include/SDL3/SDL_platform.h similarity index 58% rename from sdl/include/SDL_test_log.h rename to libs/include/SDL3/SDL_platform.h index 4c34573..9ad380b 100644 --- a/sdl/include/SDL_test_log.h +++ b/libs/include/SDL3/SDL_platform.h @@ -19,49 +19,48 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * \file SDL_test_log.h +/** + * # CategoryPlatform * - * Include file for SDL test framework. - * - * This code is a part of the SDL2_test library, not the main SDL library. + * SDL provides a means to identify the app's platform, both at compile time + * and runtime. */ -/* - * - * Wrapper to log in the TEST category - * - */ +#ifndef SDL_platform_h_ +#define SDL_platform_h_ -#ifndef SDL_test_log_h_ -#define SDL_test_log_h_ +#include -#include "begin_code.h" +#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. +/** + * Get the name of the platform. * - * \param fmt Message to be logged - */ -void 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. + * Here are the names returned for some (but not all) supported platforms: * - * \param fmt Message to be logged + * - "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". + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -void SDLTest_LogError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); /* 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: */ +#endif /* SDL_platform_h_ */ diff --git a/libs/include/SDL3/SDL_platform_defines.h b/libs/include/SDL3/SDL_platform_defines.h new file mode 100644 index 0000000..7963149 --- /dev/null +++ b/libs/include/SDL3/SDL_platform_defines.h @@ -0,0 +1,497 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 or visionOS. + * + * \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)) && !defined(__NGAGE__) + +/** + * 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 + +#ifdef __NGAGE__ + +/** + * A preprocessor macro that is only defined if compiling for the Nokia + * N-Gage. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_PLATFORM_NGAGE 1 +#endif + +#ifdef __GNU__ + +/** + * A preprocessor macro that is only defined if compiling for GNU/Hurd. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_PLATFORM_HURD 1 +#endif + +#endif /* SDL_platform_defines_h_ */ diff --git a/sdl/include/SDL_power.h b/libs/include/SDL3/SDL_power.h similarity index 57% rename from sdl/include/SDL_power.h rename to libs/include/SDL3/SDL_power.h index 0049837..0616cc2 100644 --- a/sdl/include/SDL_power.h +++ b/libs/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,30 @@ 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. * - * \since This function is available since SDL 2.0.0. + * \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 when 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. + * + * \threadsafety This function is not thread safe. + * + * \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/libs/include/SDL3/SDL_process.h b/libs/include/SDL3/SDL_process.h new file mode 100644 index 0000000..b797890 --- /dev/null +++ b/libs/include/SDL3/SDL_process.h @@ -0,0 +1,441 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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_WORKING_DIRECTORY_STRING`: a UTF-8 encoded + * string representing the working directory for the process, defaults to + * the current working directory. + * - `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. + * - `SDL_PROP_PROCESS_CREATE_CMDLINE_STRING`: a string containing the program + * to run and any parameters. This string is passed directly to + * `CreateProcess` on Windows, and does nothing on other platforms. This + * property is only important if you want to start programs that does + * non-standard command-line processing, and in most cases using + * `SDL_PROP_PROCESS_CREATE_ARGS_POINTER` is sufficient. + * + * 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_WORKING_DIRECTORY_STRING "SDL.process.create.working_directory" +#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" +#define SDL_PROP_PROCESS_CREATE_CMDLINE_STRING "SDL.process.create.cmdline" + +/** + * 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/libs/include/SDL3/SDL_properties.h b/libs/include/SDL3/SDL_properties.h new file mode 100644 index 0000000..abd7b2a --- /dev/null +++ b/libs/include/SDL3/SDL_properties.h @@ -0,0 +1,572 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 + +/** + * An ID that represents a properties set. + * + * \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; + +/** + * A generic property for naming things. + * + * This property is intended to be added to any SDL_PropertiesID that needs a + * generic name associated with the property set. It is not guaranteed that + * any property set will include this key, but it is convenient to have a + * standard key that any piece of code could reasonably agree to use. + * + * For example, the properties associated with an SDL_Texture might have a + * name string of "player sprites", or an SDL_AudioStream might have + * "background music", etc. This might also be useful for an SDL_IOStream to + * list the path to its asset. + * + * There is no format for the value set with this key; it is expected to be + * human-readable and informational in nature, possibly for logging or + * debugging purposes. + * + * SDL does not currently set this property on any objects it creates, but + * this may change in later versions; it is currently expected that apps and + * external libraries will take advantage of it, when appropriate. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_PROP_NAME_STRING "SDL.name" + +/** + * Get the global SDL properties. + * + * \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_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. This + * function acquires simultaneous mutex locks on both the source + * and destination property sets. + * + * \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/libs/include/SDL3/SDL_rect.h b/libs/include/SDL3/SDL_rect.h new file mode 100644 index 0000000..5f395ec --- /dev/null +++ b/libs/include/SDL3/SDL_rect.h @@ -0,0 +1,528 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 stored using floating point values. + * + * The origin of the coordinate space is in the top-left, with increasing + * values moving down and right. The properties `x` and `y` represent the + * coordinates of the top-left corner of the rectangle. + * + * \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 = SDL_static_cast(float, rect->x); + frect->y = SDL_static_cast(float, rect->y); + frect->w = SDL_static_cast(float, rect->w); + frect->h = SDL_static_cast(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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \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_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 takes no space. + * + * 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRectIntersectionFloat + */ +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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \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_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/libs/include/SDL3/SDL_render.h b/libs/include/SDL3/SDL_render.h new file mode 100644 index 0000000..986130c --- /dev/null +++ b/libs/include/SDL3/SDL_render.h @@ -0,0 +1,3028 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 3D 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 + +#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" + +/** + * The name of the GPU renderer. + * + * \since This macro is available since SDL 3.4.0. + */ +#define SDL_GPU_RENDERER "gpu" + +/** + * 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; + +/** + * The addressing mode for a texture when used in SDL_RenderGeometry(). + * + * This affects how texture coordinates are interpreted outside of [0, 1] + * + * Texture wrapping is always supported for power of two texture sizes, and is + * supported for other texture sizes if + * SDL_PROP_RENDERER_TEXTURE_WRAPPING_BOOLEAN is set to true. + * + * \since This enum is available since SDL 3.4.0. + */ +typedef enum SDL_TextureAddressMode +{ + SDL_TEXTURE_ADDRESS_INVALID = -1, + SDL_TEXTURE_ADDRESS_AUTO, /**< Wrapping is enabled if texture coordinates are outside [0, 1], this is the default */ + SDL_TEXTURE_ADDRESS_CLAMP, /**< Texture coordinates are clamped to the [0, 1] range */ + SDL_TEXTURE_ADDRESS_WRAP /**< The texture is repeated (tiled) */ +} SDL_TextureAddressMode; + +/** + * 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 the clear color */ + 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 SDL GPU renderer (since SDL 3.4.0): + * + * - `SDL_PROP_RENDERER_CREATE_GPU_DEVICE_POINTER`: the device to use with the + * renderer, optional. + * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_SPIRV_BOOLEAN`: the app is able to + * provide SPIR-V shaders to SDL_GPURenderState, optional. + * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_DXIL_BOOLEAN`: the app is able to + * provide DXIL shaders to SDL_GPURenderState, optional. + * - `SDL_PROP_RENDERER_CREATE_GPU_SHADERS_MSL_BOOLEAN`: the app is able to + * provide MSL shaders to SDL_GPURenderState, optional. + * + * 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_GPU_DEVICE_POINTER "SDL.renderer.create.gpu.device" +#define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_SPIRV_BOOLEAN "SDL.renderer.create.gpu.shaders_spirv" +#define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_DXIL_BOOLEAN "SDL.renderer.create.gpu.shaders_dxil" +#define SDL_PROP_RENDERER_CREATE_GPU_SHADERS_MSL_BOOLEAN "SDL.renderer.create.gpu.shaders_msl" +#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 GPU rendering context. + * + * The GPU device to use is passed in as a parameter. If this is NULL, then a + * device will be created normally and can be retrieved using + * SDL_GetGPURendererDevice(). + * + * The window to use is passed in as a parameter. If this is NULL, then this + * will become an offscreen renderer. In that case, you should call + * SDL_SetRenderTarget() to setup rendering to a texture, and then call + * SDL_RenderPresent() normally to complete drawing a frame. + * + * \param device the GPU device to use with the renderer, or NULL to create a + * device. + * \param window the window where rendering is displayed, or NULL to create an + * offscreen renderer. + * \returns a valid rendering context or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety If this function is called with a valid GPU device, it should + * be called on the thread that created the device. If this + * function is called with a valid window, it should be called + * on the thread that created the window. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_CreateRendererWithProperties + * \sa SDL_GetGPURendererDevice + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPURenderState + * \sa SDL_SetGPURenderState + */ +extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateGPURenderer(SDL_GPUDevice *device, SDL_Window *window); + +/** + * Return the GPU device used by a renderer. + * + * \param renderer the rendering context. + * \returns the GPU device used by the renderer, or NULL if the renderer is + * not a GPU renderer; 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.4.0. + */ +extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_GetGPURendererDevice(SDL_Renderer *renderer); + +/** + * 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 It is safe to call this function from any 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_TEXTURE_WRAPPING_BOOLEAN`: true if the renderer + * supports SDL_TEXTURE_ADDRESS_WRAP on non-power-of-two textures. + * - `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_TEXTURE_WRAPPING_BOOLEAN "SDL.renderer.texture_wrapping" +#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_PALETTE_POINTER`: an SDL_Palette to use with + * palettized texture formats. This can be set later with + * SDL_SetTexturePalette() + * - `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_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 associated + * with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER`: the VkImageLayout for the + * VkImage, defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. + * + * With the GPU renderer: + * + * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER`: the SDL_GPUTexture + * associated with the texture, if you want to wrap an existing texture. + * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER`: the SDL_GPUTexture + * associated with the UV plane of an NV12 texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_NUMBER`: the SDL_GPUTexture + * associated with the U plane of a YUV texture, if you want to wrap an + * existing texture. + * - `SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_NUMBER`: the SDL_GPUTexture + * associated with the V plane of a YUV 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_PALETTE_POINTER "SDL.texture.create.palette" +#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" +#define SDL_PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER "SDL.texture.create.vulkan.layout" +#define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER "SDL.texture.create.gpu.texture" +#define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_POINTER "SDL.texture.create.gpu.texture_uv" +#define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_POINTER "SDL.texture.create.gpu.texture_u" +#define SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_POINTER "SDL.texture.create.gpu.texture_v" + +/** + * 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) + * + * With the gpu renderer: + * + * - `SDL_PROP_TEXTURE_GPU_TEXTURE_POINTER`: the SDL_GPUTexture associated + * with the texture + * - `SDL_PROP_TEXTURE_GPU_TEXTURE_UV_POINTER`: the SDL_GPUTexture associated + * with the UV plane of an NV12 texture + * - `SDL_PROP_TEXTURE_GPU_TEXTURE_U_POINTER`: the SDL_GPUTexture associated + * with the U plane of a YUV texture + * - `SDL_PROP_TEXTURE_GPU_TEXTURE_V_POINTER`: the SDL_GPUTexture associated + * with the V plane of a YUV texture + * + * \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" +#define SDL_PROP_TEXTURE_GPU_TEXTURE_POINTER "SDL.texture.gpu.texture" +#define SDL_PROP_TEXTURE_GPU_TEXTURE_UV_POINTER "SDL.texture.gpu.texture_uv" +#define SDL_PROP_TEXTURE_GPU_TEXTURE_U_POINTER "SDL.texture.gpu.texture_u" +#define SDL_PROP_TEXTURE_GPU_TEXTURE_V_POINTER "SDL.texture.gpu.texture_v" + +/** + * 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 the palette used by a texture. + * + * Setting the palette keeps an internal reference to the palette, which can + * be safely destroyed afterwards. + * + * A single palette can be shared with many textures. + * + * \param texture the texture 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 should only be called on the main thread. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_CreatePalette + * \sa SDL_GetTexturePalette + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetTexturePalette(SDL_Texture *texture, SDL_Palette *palette); + +/** + * Get the palette used by a texture. + * + * \param texture the texture to query. + * \returns a pointer to the palette used by the texture, or NULL if there is + * no palette used. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_SetTexturePalette + */ +extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetTexturePalette(SDL_Texture *texture); + +/** + * 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. + * + * 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 + * 0 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 filled with the logical presentation width. + * \param h an int filled with the logical presentation height. + * \param mode a variable filled with the logical presentation mode being + * 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 if the event is converted or doesn't need conversion, 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 + * \sa SDL_RenderTexture9GridTiled + */ +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); + +/** + * 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 + * tiled 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. + * \param tileScale the scale used to transform the borders and center of + * `srcrect` into the borders and middle of `dstrect`, or + * 1.0f for an unscaled copy. + * \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.4.0. + * + * \sa SDL_RenderTexture + * \sa SDL_RenderTexture9Grid + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9GridTiled(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, float tileScale); + +/** + * 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 + * \sa SDL_SetRenderTextureAddressMode + */ +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 + * \sa SDL_SetRenderTextureAddressMode + */ +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); + +/** + * Set the texture addressing mode used in SDL_RenderGeometry(). + * + * \param renderer the rendering context. + * \param u_mode the SDL_TextureAddressMode to use for horizontal texture + * coordinates in SDL_RenderGeometry(). + * \param v_mode the SDL_TextureAddressMode to use for vertical texture + * coordinates in SDL_RenderGeometry(). + * \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.4.0. + * + * \sa SDL_RenderGeometry + * \sa SDL_RenderGeometryRaw + * \sa SDL_GetRenderTextureAddressMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTextureAddressMode(SDL_Renderer *renderer, SDL_TextureAddressMode u_mode, SDL_TextureAddressMode v_mode); + +/** + * Get the texture addressing mode used in SDL_RenderGeometry(). + * + * \param renderer the rendering context. + * \param u_mode a pointer filled in with the SDL_TextureAddressMode to use + * for horizontal texture coordinates in SDL_RenderGeometry(), + * may be NULL. + * \param v_mode a pointer filled in with the SDL_TextureAddressMode to use + * for vertical texture coordinates in SDL_RenderGeometry(), 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.4.0. + * + * \sa SDL_SetRenderTextureAddressMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderTextureAddressMode(SDL_Renderer *renderer, SDL_TextureAddressMode *u_mode, SDL_TextureAddressMode *v_mode); + +/** + * 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 fail. + * + * \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). You can use logical presentation + * or SDL_SetRenderScale() to adjust it. + * - 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 convenience 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); + +/** + * Set default scale mode for new textures for given renderer. + * + * When a renderer is created, scale_mode defaults to SDL_SCALEMODE_LINEAR. + * + * \param renderer the renderer to update. + * \param scale_mode the scale mode to change to for new textures. + * \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.4.0. + * + * \sa SDL_GetDefaultTextureScaleMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetDefaultTextureScaleMode(SDL_Renderer *renderer, SDL_ScaleMode scale_mode); + +/** + * Get default texture scale mode of the given renderer. + * + * \param renderer the renderer to get data from. + * \param scale_mode a SDL_ScaleMode filled with current default scale mode. + * See SDL_SetDefaultTextureScaleMode() 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.4.0. + * + * \sa SDL_SetDefaultTextureScaleMode + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetDefaultTextureScaleMode(SDL_Renderer *renderer, SDL_ScaleMode *scale_mode); + +/** + * A structure specifying the parameters of a GPU render state. + * + * \since This struct is available since SDL 3.4.0. + * + * \sa SDL_CreateGPURenderState + */ +typedef struct SDL_GPURenderStateCreateInfo +{ + SDL_GPUShader *fragment_shader; /**< The fragment shader to use when this render state is active */ + + Sint32 num_sampler_bindings; /**< The number of additional fragment samplers to bind when this render state is active */ + const SDL_GPUTextureSamplerBinding *sampler_bindings; /**< Additional fragment samplers to bind when this render state is active */ + + Sint32 num_storage_textures; /**< The number of storage textures to bind when this render state is active */ + SDL_GPUTexture *const *storage_textures; /**< Storage textures to bind when this render state is active */ + + Sint32 num_storage_buffers; /**< The number of storage buffers to bind when this render state is active */ + SDL_GPUBuffer *const *storage_buffers; /**< Storage buffers to bind when this render state is active */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPURenderStateCreateInfo; + +/** + * A custom GPU render state. + * + * \since This struct is available since SDL 3.4.0. + * + * \sa SDL_CreateGPURenderState + * \sa SDL_SetGPURenderStateFragmentUniforms + * \sa SDL_SetGPURenderState + * \sa SDL_DestroyGPURenderState + */ +typedef struct SDL_GPURenderState SDL_GPURenderState; + +/** + * Create custom GPU render state. + * + * \param renderer the renderer to use. + * \param createinfo a struct describing the GPU render state to create. + * \returns a custom GPU render state or NULL on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function should be called on the thread that created the + * renderer. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_SetGPURenderStateFragmentUniforms + * \sa SDL_SetGPURenderState + * \sa SDL_DestroyGPURenderState + */ +extern SDL_DECLSPEC SDL_GPURenderState * SDLCALL SDL_CreateGPURenderState(SDL_Renderer *renderer, const SDL_GPURenderStateCreateInfo *createinfo); + +/** + * Set fragment shader uniform variables in a custom GPU render state. + * + * The data is copied and will be pushed using + * SDL_PushGPUFragmentUniformData() during draw call execution. + * + * \param state the state to modify. + * \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. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should be called on the thread that created the + * renderer. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPURenderStateFragmentUniforms(SDL_GPURenderState *state, Uint32 slot_index, const void *data, Uint32 length); + +/** + * Set custom GPU render state. + * + * This function sets custom GPU render state for subsequent draw calls. This + * allows using custom shaders with the GPU renderer. + * + * \param renderer the renderer to use. + * \param state the state to to use, or NULL to clear custom GPU render state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should be called on the thread that created the + * renderer. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPURenderState(SDL_Renderer *renderer, SDL_GPURenderState *state); + +/** + * Destroy custom GPU render state. + * + * \param state the state to destroy. + * + * \threadsafety This function should be called on the thread that created the + * renderer. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_CreateGPURenderState + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPURenderState(SDL_GPURenderState *state); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_render_h_ */ diff --git a/sdl/include/SDL_name.h b/libs/include/SDL3/SDL_revision.h similarity index 73% rename from sdl/include/SDL_name.h rename to libs/include/SDL3/SDL_revision.h index 0b6b1f9..32d6988 100644 --- a/sdl/include/SDL_name.h +++ b/libs/include/SDL3/SDL_revision.h @@ -19,15 +19,21 @@ 3. This notice may not be removed or altered from any source distribution. */ -#ifndef SDLname_h_ -#define SDLname_h_ +/** + * \file SDL_revision.h + * + * Header file containing the SDL revision. + */ -#if defined(__STDC__) || defined(__cplusplus) -#define NeedFunctionPrototypes 1 +#ifndef SDL_revision_h_ +#define SDL_revision_h_ + +/* #undef SDL_VENDOR_INFO */ + +#ifdef SDL_VENDOR_INFO +#define SDL_REVISION "SDL-3.4.12-release-3.4.12 (" SDL_VENDOR_INFO ")" +#else +#define SDL_REVISION "SDL-3.4.12-release-3.4.12" #endif -#define SDL_NAME(X) SDL_##X - -#endif /* SDLname_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ +#endif /* SDL_revision_h_ */ diff --git a/sdl/include/SDL_scancode.h b/libs/include/SDL3/SDL_scancode.h similarity index 84% rename from sdl/include/SDL_scancode.h rename to libs/include/SDL3/SDL_scancode.h index 4672a62..cd5a137 100644 --- a/sdl/include/SDL_scancode.h +++ b/libs/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 { @@ -199,7 +208,7 @@ typedef enum SDL_Scancode SDL_SCANCODE_NONUSBACKSLASH = 100, /**< This is the additional key that ISO * keyboards have over ANSI ones, - * located between left shift and Y. + * located between left shift and Z. * Produces GRAVE ACCENT and TILDE in a * US or UK Mac layout, REVERSE SOLIDUS * (backslash) and VERTICAL LINE in a @@ -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/sdl/include/SDL_sensor.h b/libs/include/SDL3/SDL_sensor.h similarity index 50% rename from sdl/include/SDL_sensor.h rename to libs/include/SDL3/SDL_sensor.h index 0f37e46..bf89047 100644 --- a/sdl/include/SDL_sensor.h +++ b/libs/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 { @@ -120,187 +138,163 @@ typedef enum SDL_SensorType SDL_SENSOR_ACCEL_L, /**< Accelerometer for left Joy-Con controller and Wii nunchuk */ SDL_SENSOR_GYRO_L, /**< Gyroscope for left Joy-Con controller */ SDL_SENSOR_ACCEL_R, /**< Accelerometer for right Joy-Con controller */ - SDL_SENSOR_GYRO_R /**< Gyroscope for right Joy-Con controller */ + SDL_SENSOR_GYRO_R, /**< Gyroscope for right Joy-Con controller */ + SDL_SENSOR_COUNT } 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 + * Get a list of currently connected sensors. * - * 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. + * \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. * - * 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. + * \since This function is available since SDL 3.2.0. */ -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. - * - * \returns the number of sensors detected. - * - * \since This function is available since SDL 2.0.9. - */ -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. * - * \since This function is available since SDL 2.0.9. + * \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 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. * - * \since This function is available since SDL 2.0.9. + * \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 3.2.0. */ -extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index); - -/** - * Get the instance ID of a sensor. - * - * \param device_index The sensor to get instance id from. - * \returns the sensor instance ID, or -1 if `device_index` is out of range. - * - * \since This function is available since SDL 2.0.9. - */ -extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index); +extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); /** * Open a sensor for use. * - * \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_OpenSensor(SDL_SensorID instance_id); /** - * Return the SDL_Sensor associated with an instance id. + * Return the SDL_Sensor associated with an instance ID. * - * \param instance_id The sensor from instance id. - * \returns an SDL_Sensor object. + * \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_SensorFromInstanceID(SDL_SensorID instance_id); +extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); /** - * Get the implementation dependent name of a sensor + * Get the properties associated with 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 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 const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor); +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); + +/** + * Get the implementation dependent name of a sensor. + * + * \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 3.2.0. + */ +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 close. * - * \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. - * - * \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 +305,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 +316,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/libs/include/SDL3/SDL_stdinc.h b/libs/include/SDL3/SDL_stdinc.h new file mode 100644 index 0000000..b6403be --- /dev/null +++ b/libs/include/SDL3/SDL_stdinc.h @@ -0,0 +1,6186 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 + +/* Most everything except Visual Studio 2008 and earlier has stdint.h now */ +#if defined(_MSC_VER) && (_MSC_VER < 1600) +typedef signed __int8 int8_t; +typedef unsigned __int8 uint8_t; +typedef signed __int16 int16_t; +typedef unsigned __int16 uint16_t; +typedef signed __int32 int32_t; +typedef unsigned __int32 uint32_t; +typedef signed __int64 int64_t; +typedef unsigned __int64 uint64_t; +#ifndef _INTPTR_T_DEFINED +#ifdef _WIN64 +typedef __int64 intptr_t; +#else +typedef int intptr_t; +#endif +#endif +#ifndef _UINTPTR_T_DEFINED +#ifdef _WIN64 +typedef unsigned __int64 uintptr_t; +#else +typedef unsigned int uintptr_t; +#endif +#endif +#else +#include +#endif + +#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. + * + * \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 datatype 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, SDL_static_cast(int, ~SDL_static_cast(int, 0)) == SDL_static_cast(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 (other + * than insert `((void)(data)` so the compiler sees an expression) 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) ((void)(data)) +#elif !defined(SDL_DISABLE_ALLOCA) +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) +#define SDL_stack_free(data) ((void)(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. + * + * The name of the variable is case sensitive on all platforms. + * + * 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. + * + * On some platforms, this may make case-insensitive matches, while other + * platforms are case-sensitive. It is best to be precise with strings used + * for queries through this interface. SDL_getenv is always case-sensitive, + * however. + * + * \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 greater 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_zerop + */ +#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 hexadecimal, 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 hexadecimal, 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 hexadecimal, 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 hexadecimal, 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 hexadecimal, 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 hexadecimal, 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 occurrence 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 occurrence 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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 successful 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. + * + * \threadsafety Do not use the same SDL_iconv_t from two threads at once. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_utf8_ucs2(S) SDL_reinterpret_cast(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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_utf8_ucs4(S) SDL_reinterpret_cast(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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", SDL_reinterpret_cast(const 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 + +#if !defined(HAVE_STRTOK_R) && !defined(strtok_r) +char *strtok_r(char *str, const char *delim, char **saveptr); +#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/libs/include/SDL3/SDL_storage.h b/libs/include/SDL3/SDL_storage.h new file mode 100644 index 0000000..4391daa --- /dev/null +++ b/libs/include/SDL3/SDL_storage.h @@ -0,0 +1,686 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * By default, SDL_OpenTitleStorage uses the generic storage implementation. + * When the path override is not provided, the generic implementation will use + * the output of SDL_GetBasePath as the base path. + * + * \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 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. + * + * \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/libs/include/SDL3/SDL_surface.h b/libs/include/SDL3/SDL_surface.h new file mode 100644 index 0000000..885f8f5 --- /dev/null +++ b/libs/include/SDL3/SDL_surface.h @@ -0,0 +1,1769 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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(), and a simple .png + * loader, SDL_LoadPNG(). SDL itself does not provide loaders for other file + * formats, but there are several excellent external libraries that do, + * including its own satellite library, + * [SDL_image](https://wiki.libsdl.org/SDL3_image) + * . + * + * In general these functions are thread-safe in that they can be called on + * different threads with different surfaces. You should not try to modify any + * surface from two threads simultaneously. + */ + +#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_PIXELART /**< nearest pixel sampling with improved scaling for pixel art, available since SDL 3.4.0 */ +} 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_FLIP_HORIZONTAL_AND_VERTICAL = (SDL_FLIP_HORIZONTAL | SDL_FLIP_VERTICAL) /**< flip horizontally and vertically (not a diagonal flip) */ +} 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. + * - `SDL_PROP_SURFACE_ROTATION_FLOAT`: the number of degrees a surface's data + * is meant to be rotated clockwise to make the image right-side up. Default + * 0. This is used by the camera API, if a mobile device is oriented + * differently than what its camera provides (i.e. - the camera always + * provides portrait images but the phone is being held in landscape + * orientation). Since SDL 3.4.0. + * + * \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" +#define SDL_PROP_SURFACE_ROTATION_FLOAT "SDL.surface.rotation" + +/** + * 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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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. + * + * Setting the palette keeps an internal reference to the palette, which can + * be safely destroyed afterwards. + * + * 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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. 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 or PNG 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.4.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadSurface + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadSurface_IO(SDL_IOStream *src, bool closeio); + +/** + * Load a BMP or PNG 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 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.4.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadSurface_IO + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadSurface(const char *file); + +/** + * 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 can be called on different threads with + * different surfaces. + * + * \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 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 file a file to save to. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function can be called on different threads with + * different surfaces. + * + * \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); + +/** + * Load a PNG image from a seekable SDL data stream. + * + * This is intended as a convenience function for loading images from trusted + * sources. If you want to load arbitrary images you should use libpng or + * another image loading library designed with security in mind. + * + * 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.4.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadPNG + * \sa SDL_SavePNG_IO + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadPNG_IO(SDL_IOStream *src, bool closeio); + +/** + * Load a PNG image from a file. + * + * This is intended as a convenience function for loading images from trusted + * sources. If you want to load arbitrary images you should use libpng or + * another image loading library designed with security in mind. + * + * The new surface should be freed with SDL_DestroySurface(). Not doing so + * will result in a memory leak. + * + * \param file the PNG 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.4.0. + * + * \sa SDL_DestroySurface + * \sa SDL_LoadPNG_IO + * \sa SDL_SavePNG + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadPNG(const char *file); + +/** + * Save a surface to a seekable SDL data stream in PNG format. + * + * \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 can be called on different threads with + * different surfaces. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_LoadPNG_IO + * \sa SDL_SavePNG + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SavePNG_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); + +/** + * Save a surface to a file in PNG format. + * + * \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 can be called on different threads with + * different surfaces. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_LoadPNG + * \sa SDL_SavePNG_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SavePNG(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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); + +/** + * Return a copy of a surface rotated clockwise a number of degrees. + * + * The angle of rotation can be negative for counter-clockwise rotation. + * + * When the rotation isn't a multiple of 90 degrees, the resulting surface is + * larger than the original, with the background filled in with the colorkey, + * if available, or RGBA 255/255/255/0 if not. + * + * If `surface` has the SDL_PROP_SURFACE_ROTATION_FLOAT property set on it, + * the new copy will have the adjusted value set: if the rotation property is + * 90 and `angle` was 30, the new surface will have a property value of 60 + * (that is: to be upright vs gravity, this surface needs to rotate 60 more + * degrees). However, note that further rotations on the new surface in this + * example will produce unexpected results, since the image will have resized + * and padded to accommodate the not-90 degree angle. + * + * \param surface the surface to rotate. + * \param angle the rotation angle, in degrees. + * \returns a rotated copy of the surface or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function can be called on different threads with + * different surfaces. + * + * \since This function is available since SDL 3.4.0. + */ +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RotateSurface(SDL_Surface *surface, float angle); + +/** + * 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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 surface. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 This function can be called on different threads with + * different surfaces. + * + * \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 This function can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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 can be called on different threads with + * different surfaces. + * + * \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/libs/include/SDL3/SDL_system.h b/libs/include/SDL3/SDL_system.h new file mode 100644 index 0000000..ec23a1f --- /dev/null +++ b/libs/include/SDL3/SDL_system.h @@ -0,0 +1,840 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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`. + * + * \threadsafety This function should only be called on the main thread. + * + * \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`. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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. + * + * \threadsafety This function should only be called on the main thread. + * + * \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. + * + * \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_GetAndroidSDKVersion(void); + +/** + * Query if the application is running on a Chromebook. + * + * \returns true if this is a Chromebook, false 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 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. + * + * \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_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. + * + * \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_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. + * + * \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_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/sdl/include/SDL_test.h b/libs/include/SDL3/SDL_test.h similarity index 72% rename from sdl/include/SDL_test.h rename to libs/include/SDL3/SDL_test.h index 9857cb8..59a3dd8 100644 --- a/sdl/include/SDL_test.h +++ b/libs/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 +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include -#include "begin_code.h" +#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/sdl/include/SDL_test_assert.h b/libs/include/SDL3/SDL_test_assert.h similarity index 59% rename from sdl/include/SDL_test_assert.h rename to libs/include/SDL3/SDL_test_assert.h index 3d490db..ff41b31 100644 --- a/sdl/include/SDL_test_assert.h +++ b/libs/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 +/** + * Assertion 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. */ /* @@ -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/sdl/include/SDL_test_common.h b/libs/include/SDL3/SDL_test_common.h similarity index 51% rename from sdl/include/SDL_test_common.h rename to libs/include/SDL3/SDL_test_common.h index d4bca99..6afd857 100644 --- a/sdl/include/SDL_test_common.h +++ b/libs/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 +/** + * Common 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. */ -/* 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,23 @@ typedef struct int gl_debug; int gl_profile_mask; - /* Additional fields added in 2.0.18 */ + /* Mouse info */ SDL_Rect confine; + bool hide_cursor; + /* Misc. */ + int quit_after_ms_interval; + SDL_TimerID quit_after_ms_timer; + + /* 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 +173,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 +215,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. - * - * \param state The common state describing the test window to create. - * \returns a string with usage information - */ -const char *SDLTest_CommonUsage(SDLTest_CommonState * state); - -/* - * \brief Open test window. +/** + * Open test window. * * \param state The common state describing the test window to create. * - * \returns SDL_TRUE if initialization succeeded, false otherwise + * \returns true if initialization succeeded, false otherwise */ -SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); +bool SDLCALL SDLTest_CommonInit(SDLTest_CommonState *state); -/* - * \brief Easy argument handling when test app doesn't need any custom args. +/** + * 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_FALSE if app should quit, true otherwise. + * \returns false if app should quit, true otherwise. */ -SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv); +bool SDLCALL SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv); -/* - * \brief Common event handler for test windows. +/** + * Print the details of an event. + * + * This is automatically called by SDLTest_CommonEvent() as needed. + * + * \param event The event to print. + */ +void SDLCALL SDLTest_PrintEvent(const SDL_Event *event); + +/** + * 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 SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done); +void SDLCALL SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done); -/* - * \brief Close test window. +/** + * 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(). + */ +SDL_AppResult SDLCALL SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event); + +/** + * 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/sdl/include/SDL_test_compare.h b/libs/include/SDL3/SDL_test_compare.h similarity index 61% rename from sdl/include/SDL_test_compare.h rename to libs/include/SDL3/SDL_test_compare.h index d713e50..58e5513 100644 --- a/sdl/include/SDL_test_compare.h +++ b/libs/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 +/** + * Comparison function 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. */ /* @@ -36,18 +34,16 @@ #ifndef SDL_test_compare_h_ #define SDL_test_compare_h_ -#include "SDL.h" +#include -#include "SDL_test_images.h" - -#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,27 @@ 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); +int SDLCALL SDLTest_CompareSurfacesIgnoreTransparentPixels(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/sdl/include/SDL_test_crc32.h b/libs/include/SDL3/SDL_test_crc32.h similarity index 66% rename from sdl/include/SDL_test_crc32.h rename to libs/include/SDL3/SDL_test_crc32.h index 467b920..f563d5d 100644 --- a/sdl/include/SDL_test_crc32.h +++ b/libs/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 +/** + * CRC32 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. */ /* @@ -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/sdl/include/SDL_test_font.h b/libs/include/SDL3/SDL_test_font.h similarity index 62% rename from sdl/include/SDL_test_font.h rename to libs/include/SDL3/SDL_test_font.h index b14873a..f5b5674 100644 --- a/sdl/include/SDL_test_font.h +++ b/libs/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/sdl/include/SDL_test_fuzzer.h b/libs/include/SDL3/SDL_test_fuzzer.h similarity index 68% rename from sdl/include/SDL_test_fuzzer.h rename to libs/include/SDL3/SDL_test_fuzzer.h index 06ccbec..e8ebc45 100644 --- a/sdl/include/SDL_test_fuzzer.h +++ b/libs/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 +/** + * Fuzzer 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. */ /* @@ -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/sdl/include/SDL_test_harness.h b/libs/include/SDL3/SDL_test_harness.h similarity index 61% rename from sdl/include/SDL_test_harness.h rename to libs/include/SDL3/SDL_test_harness.h index 5706418..3771045 100644 --- a/sdl/include/SDL_test_harness.h +++ b/libs/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 +/** + * Test suite 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. */ /* @@ -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). + * 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. + * \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 * - * \param length The length of the seed string to generate - * - * \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/libs/include/SDL3/SDL_test_log.h b/libs/include/SDL3/SDL_test_log.h new file mode 100644 index 0000000..13933da --- /dev/null +++ b/libs/include/SDL3/SDL_test_log.h @@ -0,0 +1,83 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. +*/ + +/** + * Logging related functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + * + * Wrapper to log in the TEST category + * + */ + +#ifndef SDL_test_log_h_ +#define SDL_test_log_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Prints given message with a timestamp in the TEST category and given priority. + * + * \param priority Priority of the message + * \param fmt Message to be logged + */ +void SDLCALL SDLTest_LogMessage(SDL_LogPriority priority, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + +/** + * Prints given message with a timestamp in the TEST category and INFO priority. + * + * \param fmt Message to be logged + */ +void SDLCALL SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * 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 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 + +#endif /* SDL_test_log_h_ */ diff --git a/sdl/include/SDL_test_md5.h b/libs/include/SDL3/SDL_test_md5.h similarity index 82% rename from sdl/include/SDL_test_md5.h rename to libs/include/SDL3/SDL_test_md5.h index aa98c74..7b86b05 100644 --- a/sdl/include/SDL_test_md5.h +++ b/libs/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 +/** + * MD5 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. */ /* @@ -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/sdl/include/SDL_test_memory.h b/libs/include/SDL3/SDL_test_memory.h similarity index 70% rename from sdl/include/SDL_test_memory.h rename to libs/include/SDL3/SDL_test_memory.h index 0aa10de..f07f1cb 100644 --- a/sdl/include/SDL_test_memory.h +++ b/libs/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 +/** + * Memory tracking 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_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 implicitly calls SDLTest_TrackAllocations() + */ +void SDLCALL SDLTest_RandFillAllocations(void); + +/** + * Print a log of any outstanding allocations * * \note This can be called after SDL_Quit() */ -void SDLTest_LogAllocations(void); - +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/libs/include/SDL3/SDL_thread.h b/libs/include/SDL3/SDL_thread.h new file mode 100644 index 0000000..1842c03 --- /dev/null +++ b/libs/include/SDL3/SDL_thread.h @@ -0,0 +1,602 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 thread safety measures: locking and synchronization + * mechanisms are handled by the functions in SDL_mutex.h. + */ + +#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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \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_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. + * + * \threadsafety It is safe to call this function from any thread, but only a + * single thread can wait any specific thread to finish. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any 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/libs/include/SDL3/SDL_time.h b/libs/include/SDL3/SDL_time.h new file mode 100644 index 0000000..2ae6022 --- /dev/null +++ b/libs/include/SDL3/SDL_time.h @@ -0,0 +1,249 @@ +/* +Simple DirectMedia Layer +Copyright (C) 1997-2026 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. + * + * \threadsafety This function is not thread safe. + * + * \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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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. + * + * \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_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/libs/include/SDL3/SDL_timer.h b/libs/include/SDL3/SDL_timer.h new file mode 100644 index 0000000..dfeec31 --- /dev/null +++ b/libs/include/SDL3/SDL_timer.h @@ -0,0 +1,454 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 elapsed + * (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 that have elapsed since the SDL library + * initialization. + * + * \returns an unsigned 64‑bit integer that represents the number of + * milliseconds that have elapsed since the SDL library was + * initialized (typically via a call to SDL_Init). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTicksNS + */ +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/libs/include/SDL3/SDL_touch.h b/libs/include/SDL3/SDL_touch.h new file mode 100644 index 0000000..e5576a5 --- /dev/null +++ b/libs/include/SDL3/SDL_touch.h @@ -0,0 +1,184 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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/libs/include/SDL3/SDL_tray.h b/libs/include/SDL3/SDL_tray.h new file mode 100644 index 0000000..688278a --- /dev/null +++ b/libs/include/SDL3/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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/libs/include/SDL3/SDL_version.h b/libs/include/SDL3/SDL_version.h new file mode 100644 index 0000000..cd6ae31 --- /dev/null +++ b/libs/include/SDL3/SDL_version.h @@ -0,0 +1,198 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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 4 + +/** + * 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 12 + +/** + * 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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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 the SDL library that is linked against your + * program. + * + * This value is the revision of the code you are linking against and may be + * different from the code you are compiling with, which is found in the + * constant SDL_REVISION if you explicitly include SDL_revision.h + * + * The revision is an 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. + * + * \threadsafety It is safe to call this function from any thread. + * + * \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/libs/include/SDL3/SDL_video.h b/libs/include/SDL3/SDL_video.h new file mode 100644 index 0000000..2f06295 --- /dev/null +++ b/libs/include/SDL3/SDL_video.h @@ -0,0 +1,3497 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2026 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. + * + * \since This macro is available since SDL 3.2.0. + */ +#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. + * + * When creating windows with `SDL_WINDOW_RESIZABLE`, SDL will constrain + * resizable windows to the dimensions recommended by the compositor to fit it + * within the usable desktop space, although some compositors will do this + * automatically without intervention as well. Use `SDL_SetWindowResizable` + * after creation instead if you wish to create a window with a specific size. + * + * \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_FILL_DOCUMENT SDL_UINT64_C(0x0000000000200000) /**< window is in fill-document mode (Emscripten only), since SDL 3.4.0 */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_SetWindowPosition + */ +#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. + * + * \sa SDL_GetWindowPosition + */ +#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; + +/** + * Window progress state + * + * \since This enum is available since SDL 3.2.8. + */ +typedef enum SDL_ProgressState +{ + SDL_PROGRESS_STATE_INVALID = -1, /**< An invalid progress state indicating an error; check SDL_GetError() */ + SDL_PROGRESS_STATE_NONE, /**< No progress bar is shown */ + SDL_PROGRESS_STATE_INDETERMINATE, /**< The progress bar is shown in a indeterminate state */ + SDL_PROGRESS_STATE_NORMAL, /**< The progress bar is shown in a normal state */ + SDL_PROGRESS_STATE_PAUSED, /**< The progress bar is shown in a paused state */ + SDL_PROGRESS_STATE_ERROR /**< The progress bar is shown in a state indicating the application had an error */ +} SDL_ProgressState; + +/** + * An opaque handle to an OpenGL context. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GL_CreateContext + * \sa SDL_GL_SetAttribute + * \sa SDL_GL_MakeCurrent + * \sa SDL_GL_DestroyContext + */ +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 if 1. Defaults to -1 ("don't care"). This is a request; GL drivers might not comply! */ + 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**, or NULL if + * index is out of bounds. + * + * \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. + * + * On Wayland: + * + * - `SDL_PROP_DISPLAY_WAYLAND_WL_OUTPUT_POINTER`: the wl_output associated + * with the display + * + * On Windows: + * + * - `SDL_PROP_DISPLAY_WINDOWS_HMONITOR_POINTER`: the monitor handle + * (HMONITOR) associated with the display + * + * \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" +#define SDL_PROP_DISPLAY_WAYLAND_WL_OUTPUT_POINTER "SDL.display.wayland.wl_output" +#define SDL_PROP_DISPLAY_WINDOWS_HMONITOR_POINTER "SDL.display.windows.hmonitor" + +/** + * 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_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 will be shown if SDL_WINDOW_HIDDEN is not set. If hidden at + * creation time, SDL_ShowWindow() can be used to show it later. + * + * 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 iOS, tvOS, and visionOS: + * + * - `SDL_PROP_WINDOW_CREATE_WINDOWSCENE_POINTER`: the `(__unsafe_unretained)` + * UIWindowScene associated with the window, defaults to the active window + * scene. + * + * 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. + * + * These are additional supported properties with Emscripten: + * + * - `SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_CANVAS_ID_STRING`: the id given to the + * canvas element. This should start with a '#' sign + * - `SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING`: override the + * binding element for keyboard inputs for this canvas. 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. 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_WINDOWSCENE_POINTER "SDL.window.create.uikit.windowscene" +#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" +#define SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_CANVAS_ID_STRING "SDL.window.create.emscripten.canvas_id" +#define SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING "SDL.window.create.emscripten.keyboard_element" + +/** + * 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 + * associated with metal views on the window + * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER`: 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 + * + * On Emscripten: + * + * - `SDL_PROP_WINDOW_EMSCRIPTEN_CANVAS_ID_STRING`: the id the canvas element + * will have + * - `SDL_PROP_WINDOW_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING`: the keyboard + * element that associates keyboard events to this 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_NUMBER "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" +#define SDL_PROP_WINDOW_EMSCRIPTEN_CANVAS_ID_STRING "SDL.window.emscripten.canvas_id" +#define SDL_PROP_WINDOW_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING "SDL.window.emscripten.keyboard_element" + +/** + * 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_SetWindowFillDocument + * \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 added + * using SDL_AddSurfaceAlternateImage(), 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. + * + * \sa SDL_AddSurfaceAlternateImage + */ +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 + * \sa SDL_EVENT_WINDOW_RESIZED + */ +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 interactable 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 aspect ratio 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); + +/** + * Set the window to fill the current document space (Emscripten only). + * + * This will add or remove the window's `SDL_WINDOW_FILL_DOCUMENT` flag. + * + * Currently this flag only applies to the Emscripten target. + * + * When enabled, the canvas element fills the entire document. Resize events + * will be generated as the browser window is resized, as that will adjust the + * canvas size as well. The canvas will cover anything else on the page, + * including any controls provided by Emscripten in its generated HTML file + * (in fact, any elements on the page that aren't the canvas will be moved + * into a hidden `div` element). + * + * Often times this is desirable for a browser-based game, but it means + * several things that we expect of an SDL window on other platforms might not + * work as expected, such as minimum window sizes and aspect ratios. + * + * \param window the window of which to change the fill-document state. + * \param fill true to set the window to fill the document, 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.4.0. + * + * \sa SDL_GetWindowFlags + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFillDocument(SDL_Window *window, bool fill); + +/** + * 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_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); + +/** + * Sets the state of the progress bar for the given window’s taskbar icon. + * + * \param window the window whose progress state is to be modified. + * \param state the progress state. `SDL_PROGRESS_STATE_NONE` stops displaying + * the progress bar. + * \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.4.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowProgressState(SDL_Window *window, SDL_ProgressState state); + +/** + * Get the state of the progress bar for the given window’s taskbar icon. + * + * \param window the window to get the current progress state from. + * \returns the progress state, or `SDL_PROGRESS_STATE_INVALID` 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.4.0. + */ +extern SDL_DECLSPEC SDL_ProgressState SDLCALL SDL_GetWindowProgressState(SDL_Window *window); + +/** + * Sets the value of the progress bar for the given window’s taskbar icon. + * + * \param window the window whose progress value is to be modified. + * \param value the progress value in the range of [0.0f - 1.0f]. If the value + * is outside the valid range, it gets clamped. + * \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.4.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowProgressValue(SDL_Window *window, float value); + +/** + * Get the value of the progress bar for the given window’s taskbar icon. + * + * \param window the window to get the current progress value from. + * \returns the progress value in the range of [0.0f - 1.0f], 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.4.0. + */ +extern SDL_DECLSPEC float SDLCALL SDL_GetWindowProgressValue(SDL_Window *window); + +/** + * 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 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_CreateContext + * \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. + * + * The OpenGL context will be created with the current states set through + * SDL_GL_SetAttribute(). + * + * The SDL_Window specified must have been created with the SDL_WINDOW_OPENGL + * flag, or context creation will fail. + * + * 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/libs/include/SDL3/SDL_vulkan.h b/libs/include/SDL3/SDL_vulkan.h new file mode 100644 index 0000000..e91e148 --- /dev/null +++ b/libs/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/sdl/lib/x86_64-linux/libSDL2.a b/libs/lib/x86_64-linux/libSDL3.a similarity index 57% rename from sdl/lib/x86_64-linux/libSDL2.a rename to libs/lib/x86_64-linux/libSDL3.a index efcdf3b..962d0ca 100644 Binary files a/sdl/lib/x86_64-linux/libSDL2.a and b/libs/lib/x86_64-linux/libSDL3.a differ diff --git a/sdl/include/SDL.h b/sdl/include/SDL.h deleted file mode 100644 index e18e7ba..0000000 --- a/sdl/include/SDL.h +++ /dev/null @@ -1,234 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_assert.h b/sdl/include/SDL_assert.h deleted file mode 100644 index 3a84462..0000000 --- a/sdl/include/SDL_assert.h +++ /dev/null @@ -1,324 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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, NULL, 0, NULL, NULL }; \ - 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/sdl/include/SDL_atomic.h b/sdl/include/SDL_atomic.h deleted file mode 100644 index e173090..0000000 --- a/sdl/include/SDL_atomic.h +++ /dev/null @@ -1,408 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_audio.h b/sdl/include/SDL_audio.h deleted file mode 100644 index e4a2bbc..0000000 --- a/sdl/include/SDL_audio.h +++ /dev/null @@ -1,1502 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_clipboard.h b/sdl/include/SDL_clipboard.h deleted file mode 100644 index 0ad1e60..0000000 --- a/sdl/include/SDL_clipboard.h +++ /dev/null @@ -1,141 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config.h b/sdl/include/SDL_config.h deleted file mode 100644 index a628d86..0000000 --- a/sdl/include/SDL_config.h +++ /dev/null @@ -1,59 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* WIKI CATEGORY: - */ - -/* 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" -#else -/* This is a minimal configuration just to get SDL running on new platforms. */ -#include "SDL_config_minimal.h" -#endif /* platform config */ - -#ifdef USING_GENERATED_CONFIG_H -#error Wrong SDL_config.h, check your include path? -#endif - -#endif /* SDL_config_h_ */ diff --git a/sdl/include/SDL_config.h.cmake b/sdl/include/SDL_config.h.cmake deleted file mode 100644 index 4468abb..0000000 --- a/sdl/include/SDL_config.h.cmake +++ /dev/null @@ -1,571 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_h_ -#define SDL_config_h_ - -/** - * \file SDL_config.h.in - * - * This is a set of defines to configure the SDL features - */ - -/* General platform specific identifiers */ -#include "SDL_platform.h" - -/* C language features */ -#cmakedefine const @HAVE_CONST@ -#cmakedefine inline @HAVE_INLINE@ -#cmakedefine volatile @HAVE_VOLATILE@ - -/* C datatypes */ -/* Define SIZEOF_VOIDP for 64/32 architectures */ -#if defined(__LP64__) || defined(_LP64) || defined(_WIN64) -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -#cmakedefine HAVE_GCC_ATOMICS @HAVE_GCC_ATOMICS@ -#cmakedefine HAVE_GCC_SYNC_LOCK_TEST_AND_SET @HAVE_GCC_SYNC_LOCK_TEST_AND_SET@ - -/* Comment this if you want to build without any C library requirements */ -#cmakedefine HAVE_LIBC 1 -#ifdef HAVE_LIBC - -/* Useful headers */ -#cmakedefine STDC_HEADERS 1 -#cmakedefine HAVE_ALLOCA_H 1 -#cmakedefine HAVE_CTYPE_H 1 -#cmakedefine HAVE_FLOAT_H 1 -#cmakedefine HAVE_ICONV_H 1 -#cmakedefine HAVE_INTTYPES_H 1 -#cmakedefine HAVE_LIMITS_H 1 -#cmakedefine HAVE_MALLOC_H 1 -#cmakedefine HAVE_MATH_H 1 -#cmakedefine HAVE_MEMORY_H 1 -#cmakedefine HAVE_SIGNAL_H 1 -#cmakedefine HAVE_STDARG_H 1 -#cmakedefine HAVE_STDDEF_H 1 -#cmakedefine HAVE_STDINT_H 1 -#cmakedefine HAVE_STDIO_H 1 -#cmakedefine HAVE_STDLIB_H 1 -#cmakedefine HAVE_STRINGS_H 1 -#cmakedefine HAVE_STRING_H 1 -#cmakedefine HAVE_SYS_TYPES_H 1 -#cmakedefine HAVE_WCHAR_H 1 -#cmakedefine HAVE_LINUX_INPUT_H 1 -#cmakedefine HAVE_PTHREAD_NP_H 1 -#cmakedefine HAVE_LIBUNWIND_H 1 - -/* C library functions */ -#cmakedefine HAVE_DLOPEN 1 -#cmakedefine HAVE_MALLOC 1 -#cmakedefine HAVE_CALLOC 1 -#cmakedefine HAVE_REALLOC 1 -#cmakedefine HAVE_FREE 1 -#cmakedefine HAVE_ALLOCA 1 -#ifndef __WIN32__ /* Don't use C runtime versions of these on Windows */ -#cmakedefine HAVE_GETENV 1 -#cmakedefine HAVE_SETENV 1 -#cmakedefine HAVE_PUTENV 1 -#cmakedefine HAVE_UNSETENV 1 -#endif -#cmakedefine HAVE_QSORT 1 -#cmakedefine HAVE_BSEARCH 1 -#cmakedefine HAVE_ABS 1 -#cmakedefine HAVE_BCOPY 1 -#cmakedefine HAVE_MEMSET 1 -#cmakedefine HAVE_MEMCPY 1 -#cmakedefine HAVE_MEMMOVE 1 -#cmakedefine HAVE_MEMCMP 1 -#cmakedefine HAVE_WCSLEN 1 -#cmakedefine HAVE_WCSLCPY 1 -#cmakedefine HAVE_WCSLCAT 1 -#cmakedefine HAVE__WCSDUP 1 -#cmakedefine HAVE_WCSDUP 1 -#cmakedefine HAVE_WCSSTR 1 -#cmakedefine HAVE_WCSCMP 1 -#cmakedefine HAVE_WCSNCMP 1 -#cmakedefine HAVE_WCSCASECMP 1 -#cmakedefine HAVE__WCSICMP 1 -#cmakedefine HAVE_WCSNCASECMP 1 -#cmakedefine HAVE__WCSNICMP 1 -#cmakedefine HAVE_STRLEN 1 -#cmakedefine HAVE_STRLCPY 1 -#cmakedefine HAVE_STRLCAT 1 -#cmakedefine HAVE__STRREV 1 -#cmakedefine HAVE__STRUPR 1 -#cmakedefine HAVE__STRLWR 1 -#cmakedefine HAVE_INDEX 1 -#cmakedefine HAVE_RINDEX 1 -#cmakedefine HAVE_STRCHR 1 -#cmakedefine HAVE_STRRCHR 1 -#cmakedefine HAVE_STRSTR 1 -#cmakedefine HAVE_STRTOK_R 1 -#cmakedefine HAVE_ITOA 1 -#cmakedefine HAVE__LTOA 1 -#cmakedefine HAVE__UITOA 1 -#cmakedefine HAVE__ULTOA 1 -#cmakedefine HAVE_STRTOL 1 -#cmakedefine HAVE_STRTOUL 1 -#cmakedefine HAVE__I64TOA 1 -#cmakedefine HAVE__UI64TOA 1 -#cmakedefine HAVE_STRTOLL 1 -#cmakedefine HAVE_STRTOULL 1 -#cmakedefine HAVE_STRTOD 1 -#cmakedefine HAVE_ATOI 1 -#cmakedefine HAVE_ATOF 1 -#cmakedefine HAVE_STRCMP 1 -#cmakedefine HAVE_STRNCMP 1 -#cmakedefine HAVE__STRICMP 1 -#cmakedefine HAVE_STRCASECMP 1 -#cmakedefine HAVE__STRNICMP 1 -#cmakedefine HAVE_STRNCASECMP 1 -#cmakedefine HAVE_STRCASESTR 1 -#cmakedefine HAVE_SSCANF 1 -#cmakedefine HAVE_VSSCANF 1 -#cmakedefine HAVE_VSNPRINTF 1 -#cmakedefine HAVE_M_PI 1 -#cmakedefine HAVE_ACOS 1 -#cmakedefine HAVE_ACOSF 1 -#cmakedefine HAVE_ASIN 1 -#cmakedefine HAVE_ASINF 1 -#cmakedefine HAVE_ATAN 1 -#cmakedefine HAVE_ATANF 1 -#cmakedefine HAVE_ATAN2 1 -#cmakedefine HAVE_ATAN2F 1 -#cmakedefine HAVE_CEIL 1 -#cmakedefine HAVE_CEILF 1 -#cmakedefine HAVE_COPYSIGN 1 -#cmakedefine HAVE_COPYSIGNF 1 -#cmakedefine HAVE_COS 1 -#cmakedefine HAVE_COSF 1 -#cmakedefine HAVE_EXP 1 -#cmakedefine HAVE_EXPF 1 -#cmakedefine HAVE_FABS 1 -#cmakedefine HAVE_FABSF 1 -#cmakedefine HAVE_FLOOR 1 -#cmakedefine HAVE_FLOORF 1 -#cmakedefine HAVE_FMOD 1 -#cmakedefine HAVE_FMODF 1 -#cmakedefine HAVE_LOG 1 -#cmakedefine HAVE_LOGF 1 -#cmakedefine HAVE_LOG10 1 -#cmakedefine HAVE_LOG10F 1 -#cmakedefine HAVE_LROUND 1 -#cmakedefine HAVE_LROUNDF 1 -#cmakedefine HAVE_POW 1 -#cmakedefine HAVE_POWF 1 -#cmakedefine HAVE_ROUND 1 -#cmakedefine HAVE_ROUNDF 1 -#cmakedefine HAVE_SCALBN 1 -#cmakedefine HAVE_SCALBNF 1 -#cmakedefine HAVE_SIN 1 -#cmakedefine HAVE_SINF 1 -#cmakedefine HAVE_SQRT 1 -#cmakedefine HAVE_SQRTF 1 -#cmakedefine HAVE_TAN 1 -#cmakedefine HAVE_TANF 1 -#cmakedefine HAVE_TRUNC 1 -#cmakedefine HAVE_TRUNCF 1 -#cmakedefine HAVE_FOPEN64 1 -#cmakedefine HAVE_FSEEKO 1 -#cmakedefine HAVE_FSEEKO64 1 -#cmakedefine HAVE_MEMFD_CREATE 1 -#cmakedefine HAVE_POSIX_FALLOCATE 1 -#cmakedefine HAVE_SIGACTION 1 -#cmakedefine HAVE_SIGTIMEDWAIT 1 -#cmakedefine HAVE_SA_SIGACTION 1 -#cmakedefine HAVE_SETJMP 1 -#cmakedefine HAVE_NANOSLEEP 1 -#cmakedefine HAVE_SYSCONF 1 -#cmakedefine HAVE_SYSCTLBYNAME 1 -#cmakedefine HAVE_CLOCK_GETTIME 1 -#cmakedefine HAVE_GETPAGESIZE 1 -#cmakedefine HAVE_MPROTECT 1 -#cmakedefine HAVE_ICONV 1 -#cmakedefine SDL_USE_LIBICONV 1 -#cmakedefine HAVE_PTHREAD_SETNAME_NP 1 -#cmakedefine HAVE_PTHREAD_SET_NAME_NP 1 -#cmakedefine HAVE_SEM_TIMEDWAIT 1 -#cmakedefine HAVE_GETAUXVAL 1 -#cmakedefine HAVE_ELF_AUX_INFO 1 -#cmakedefine HAVE_POLL 1 -#cmakedefine HAVE__EXIT 1 - -#else -#cmakedefine HAVE_STDARG_H 1 -#cmakedefine HAVE_STDDEF_H 1 -#cmakedefine HAVE_STDINT_H 1 -#cmakedefine HAVE_FLOAT_H 1 -#endif /* HAVE_LIBC */ - -#cmakedefine HAVE_ALTIVEC_H 1 -#cmakedefine HAVE_DBUS_DBUS_H 1 -#cmakedefine HAVE_FCITX 1 -#cmakedefine HAVE_IBUS_IBUS_H 1 -#cmakedefine HAVE_SYS_INOTIFY_H 1 -#cmakedefine HAVE_INOTIFY_INIT 1 -#cmakedefine HAVE_INOTIFY_INIT1 1 -#cmakedefine HAVE_INOTIFY 1 -#cmakedefine HAVE_LIBUSB 1 -#cmakedefine HAVE_O_CLOEXEC 1 - -/* Apple platforms might be building universal binaries, where Intel builds - can use immintrin.h but other architectures can't. */ -#ifdef __APPLE__ -# if defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 -# endif -# endif -#else /* non-Apple platforms can use the normal CMake check for this. */ -#cmakedefine HAVE_IMMINTRIN_H 1 -#endif - -#cmakedefine HAVE_LIBUDEV_H 1 -#cmakedefine HAVE_LIBSAMPLERATE_H 1 -#cmakedefine HAVE_LIBDECOR_H 1 - -#cmakedefine HAVE_D3D_H @HAVE_D3D_H@ -#cmakedefine HAVE_D3D11_H @HAVE_D3D11_H@ -#cmakedefine HAVE_D3D12_H @HAVE_D3D12_H@ -#cmakedefine HAVE_DDRAW_H @HAVE_DDRAW_H@ -#cmakedefine HAVE_DSOUND_H @HAVE_DSOUND_H@ -#cmakedefine HAVE_DINPUT_H @HAVE_DINPUT_H@ -#cmakedefine HAVE_XINPUT_H @HAVE_XINPUT_H@ -#cmakedefine HAVE_WINDOWS_GAMING_INPUT_H @HAVE_WINDOWS_GAMING_INPUT_H@ -#cmakedefine HAVE_DXGI_H @HAVE_DXGI_H@ - -#cmakedefine HAVE_MMDEVICEAPI_H @HAVE_MMDEVICEAPI_H@ -#cmakedefine HAVE_AUDIOCLIENT_H @HAVE_AUDIOCLIENT_H@ -#cmakedefine HAVE_TPCSHRD_H @HAVE_TPCSHRD_H@ -#cmakedefine HAVE_SENSORSAPI_H @HAVE_SENSORSAPI_H@ -#cmakedefine HAVE_ROAPI_H @HAVE_ROAPI_H@ -#cmakedefine HAVE_SHELLSCALINGAPI_H @HAVE_SHELLSCALINGAPI_H@ - -#cmakedefine USE_POSIX_SPAWN @USE_POSIX_SPAWN@ - -/* SDL internal assertion support */ -#if @SDL_DEFAULT_ASSERT_LEVEL_CONFIGURED@ -#cmakedefine SDL_DEFAULT_ASSERT_LEVEL @SDL_DEFAULT_ASSERT_LEVEL@ -#endif - -/* Allow disabling of core subsystems */ -#cmakedefine SDL_ATOMIC_DISABLED @SDL_ATOMIC_DISABLED@ -#cmakedefine SDL_AUDIO_DISABLED @SDL_AUDIO_DISABLED@ -#cmakedefine SDL_CPUINFO_DISABLED @SDL_CPUINFO_DISABLED@ -#cmakedefine SDL_EVENTS_DISABLED @SDL_EVENTS_DISABLED@ -#cmakedefine SDL_FILE_DISABLED @SDL_FILE_DISABLED@ -#cmakedefine SDL_JOYSTICK_DISABLED @SDL_JOYSTICK_DISABLED@ -#cmakedefine SDL_HAPTIC_DISABLED @SDL_HAPTIC_DISABLED@ -#cmakedefine SDL_HIDAPI_DISABLED @SDL_HIDAPI_DISABLED@ -#cmakedefine SDL_SENSOR_DISABLED @SDL_SENSOR_DISABLED@ -#cmakedefine SDL_LOADSO_DISABLED @SDL_LOADSO_DISABLED@ -#cmakedefine SDL_RENDER_DISABLED @SDL_RENDER_DISABLED@ -#cmakedefine SDL_THREADS_DISABLED @SDL_THREADS_DISABLED@ -#cmakedefine SDL_TIMERS_DISABLED @SDL_TIMERS_DISABLED@ -#cmakedefine SDL_VIDEO_DISABLED @SDL_VIDEO_DISABLED@ -#cmakedefine SDL_POWER_DISABLED @SDL_POWER_DISABLED@ -#cmakedefine SDL_FILESYSTEM_DISABLED @SDL_FILESYSTEM_DISABLED@ -#cmakedefine SDL_LOCALE_DISABLED @SDL_LOCALE_DISABLED@ -#cmakedefine SDL_MISC_DISABLED @SDL_MISC_DISABLED@ - -/* Enable various audio drivers */ -#cmakedefine SDL_AUDIO_DRIVER_ALSA @SDL_AUDIO_DRIVER_ALSA@ -#cmakedefine SDL_AUDIO_DRIVER_ALSA_DYNAMIC @SDL_AUDIO_DRIVER_ALSA_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_ANDROID @SDL_AUDIO_DRIVER_ANDROID@ -#cmakedefine SDL_AUDIO_DRIVER_OPENSLES @SDL_AUDIO_DRIVER_OPENSLES@ -#cmakedefine SDL_AUDIO_DRIVER_AAUDIO @SDL_AUDIO_DRIVER_AAUDIO@ -#cmakedefine SDL_AUDIO_DRIVER_ARTS @SDL_AUDIO_DRIVER_ARTS@ -#cmakedefine SDL_AUDIO_DRIVER_ARTS_DYNAMIC @SDL_AUDIO_DRIVER_ARTS_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_COREAUDIO @SDL_AUDIO_DRIVER_COREAUDIO@ -#cmakedefine SDL_AUDIO_DRIVER_DISK @SDL_AUDIO_DRIVER_DISK@ -#cmakedefine SDL_AUDIO_DRIVER_DSOUND @SDL_AUDIO_DRIVER_DSOUND@ -#cmakedefine SDL_AUDIO_DRIVER_DUMMY @SDL_AUDIO_DRIVER_DUMMY@ -#cmakedefine SDL_AUDIO_DRIVER_EMSCRIPTEN @SDL_AUDIO_DRIVER_EMSCRIPTEN@ -#cmakedefine SDL_AUDIO_DRIVER_ESD @SDL_AUDIO_DRIVER_ESD@ -#cmakedefine SDL_AUDIO_DRIVER_ESD_DYNAMIC @SDL_AUDIO_DRIVER_ESD_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_FUSIONSOUND @SDL_AUDIO_DRIVER_FUSIONSOUND@ -#cmakedefine SDL_AUDIO_DRIVER_FUSIONSOUND_DYNAMIC @SDL_AUDIO_DRIVER_FUSIONSOUND_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_HAIKU @SDL_AUDIO_DRIVER_HAIKU@ -#cmakedefine SDL_AUDIO_DRIVER_JACK @SDL_AUDIO_DRIVER_JACK@ -#cmakedefine SDL_AUDIO_DRIVER_JACK_DYNAMIC @SDL_AUDIO_DRIVER_JACK_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_NAS @SDL_AUDIO_DRIVER_NAS@ -#cmakedefine SDL_AUDIO_DRIVER_NAS_DYNAMIC @SDL_AUDIO_DRIVER_NAS_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_NETBSD @SDL_AUDIO_DRIVER_NETBSD@ -#cmakedefine SDL_AUDIO_DRIVER_OSS @SDL_AUDIO_DRIVER_OSS@ -#cmakedefine SDL_AUDIO_DRIVER_PAUDIO @SDL_AUDIO_DRIVER_PAUDIO@ -#cmakedefine SDL_AUDIO_DRIVER_PIPEWIRE @SDL_AUDIO_DRIVER_PIPEWIRE@ -#cmakedefine SDL_AUDIO_DRIVER_PIPEWIRE_DYNAMIC @SDL_AUDIO_DRIVER_PIPEWIRE_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_PULSEAUDIO @SDL_AUDIO_DRIVER_PULSEAUDIO@ -#cmakedefine SDL_AUDIO_DRIVER_PULSEAUDIO_DYNAMIC @SDL_AUDIO_DRIVER_PULSEAUDIO_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_QSA @SDL_AUDIO_DRIVER_QSA@ -#cmakedefine SDL_AUDIO_DRIVER_SNDIO @SDL_AUDIO_DRIVER_SNDIO@ -#cmakedefine SDL_AUDIO_DRIVER_SNDIO_DYNAMIC @SDL_AUDIO_DRIVER_SNDIO_DYNAMIC@ -#cmakedefine SDL_AUDIO_DRIVER_SUNAUDIO @SDL_AUDIO_DRIVER_SUNAUDIO@ -#cmakedefine SDL_AUDIO_DRIVER_WASAPI @SDL_AUDIO_DRIVER_WASAPI@ -#cmakedefine SDL_AUDIO_DRIVER_WINMM @SDL_AUDIO_DRIVER_WINMM@ -#cmakedefine SDL_AUDIO_DRIVER_OS2 @SDL_AUDIO_DRIVER_OS2@ -#cmakedefine SDL_AUDIO_DRIVER_VITA @SDL_AUDIO_DRIVER_VITA@ -#cmakedefine SDL_AUDIO_DRIVER_PSP @SDL_AUDIO_DRIVER_PSP@ -#cmakedefine SDL_AUDIO_DRIVER_PS2 @SDL_AUDIO_DRIVER_PS2@ -#cmakedefine SDL_AUDIO_DRIVER_N3DS @SDL_AUDIO_DRIVER_N3DS@ - -/* Enable various input drivers */ -#cmakedefine SDL_INPUT_LINUXEV @SDL_INPUT_LINUXEV@ -#cmakedefine SDL_INPUT_LINUXKD @SDL_INPUT_LINUXKD@ -#cmakedefine SDL_INPUT_FBSDKBIO @SDL_INPUT_FBSDKBIO@ -#cmakedefine SDL_INPUT_WSCONS @SDL_INPUT_WSCONS@ -#cmakedefine SDL_JOYSTICK_ANDROID @SDL_JOYSTICK_ANDROID@ -#cmakedefine SDL_JOYSTICK_HAIKU @SDL_JOYSTICK_HAIKU@ -#cmakedefine SDL_JOYSTICK_WGI @SDL_JOYSTICK_WGI@ -#cmakedefine SDL_JOYSTICK_DINPUT @SDL_JOYSTICK_DINPUT@ -#cmakedefine SDL_JOYSTICK_XINPUT @SDL_JOYSTICK_XINPUT@ -#cmakedefine SDL_JOYSTICK_DUMMY @SDL_JOYSTICK_DUMMY@ -#cmakedefine SDL_JOYSTICK_IOKIT @SDL_JOYSTICK_IOKIT@ -#cmakedefine SDL_JOYSTICK_MFI @SDL_JOYSTICK_MFI@ -#cmakedefine SDL_JOYSTICK_LINUX @SDL_JOYSTICK_LINUX@ -#cmakedefine SDL_JOYSTICK_OS2 @SDL_JOYSTICK_OS2@ -#cmakedefine SDL_JOYSTICK_USBHID @SDL_JOYSTICK_USBHID@ -#cmakedefine SDL_HAVE_MACHINE_JOYSTICK_H @SDL_HAVE_MACHINE_JOYSTICK_H@ -#cmakedefine SDL_JOYSTICK_HIDAPI @SDL_JOYSTICK_HIDAPI@ -#cmakedefine SDL_JOYSTICK_RAWINPUT @SDL_JOYSTICK_RAWINPUT@ -#cmakedefine SDL_JOYSTICK_EMSCRIPTEN @SDL_JOYSTICK_EMSCRIPTEN@ -#cmakedefine SDL_JOYSTICK_VIRTUAL @SDL_JOYSTICK_VIRTUAL@ -#cmakedefine SDL_JOYSTICK_VITA @SDL_JOYSTICK_VITA@ -#cmakedefine SDL_JOYSTICK_PSP @SDL_JOYSTICK_PSP@ -#cmakedefine SDL_JOYSTICK_PS2 @SDL_JOYSTICK_PS2@ -#cmakedefine SDL_JOYSTICK_N3DS @SDL_JOYSTICK_N3DS@ -#cmakedefine SDL_HAPTIC_DUMMY @SDL_HAPTIC_DUMMY@ -#cmakedefine SDL_HAPTIC_LINUX @SDL_HAPTIC_LINUX@ -#cmakedefine SDL_HAPTIC_IOKIT @SDL_HAPTIC_IOKIT@ -#cmakedefine SDL_HAPTIC_DINPUT @SDL_HAPTIC_DINPUT@ -#cmakedefine SDL_HAPTIC_XINPUT @SDL_HAPTIC_XINPUT@ -#cmakedefine SDL_HAPTIC_ANDROID @SDL_HAPTIC_ANDROID@ -#cmakedefine SDL_LIBUSB_DYNAMIC @SDL_LIBUSB_DYNAMIC@ -#cmakedefine SDL_UDEV_DYNAMIC @SDL_UDEV_DYNAMIC@ - -/* Enable various sensor drivers */ -#cmakedefine SDL_SENSOR_ANDROID @SDL_SENSOR_ANDROID@ -#cmakedefine SDL_SENSOR_COREMOTION @SDL_SENSOR_COREMOTION@ -#cmakedefine SDL_SENSOR_WINDOWS @SDL_SENSOR_WINDOWS@ -#cmakedefine SDL_SENSOR_DUMMY @SDL_SENSOR_DUMMY@ -#cmakedefine SDL_SENSOR_VITA @SDL_SENSOR_VITA@ -#cmakedefine SDL_SENSOR_N3DS @SDL_SENSOR_N3DS@ - -/* Enable various shared object loading systems */ -#cmakedefine SDL_LOADSO_DLOPEN @SDL_LOADSO_DLOPEN@ -#cmakedefine SDL_LOADSO_DUMMY @SDL_LOADSO_DUMMY@ -#cmakedefine SDL_LOADSO_LDG @SDL_LOADSO_LDG@ -#cmakedefine SDL_LOADSO_WINDOWS @SDL_LOADSO_WINDOWS@ -#cmakedefine SDL_LOADSO_OS2 @SDL_LOADSO_OS2@ - -/* Enable various threading systems */ -#cmakedefine SDL_THREAD_GENERIC_COND_SUFFIX @SDL_THREAD_GENERIC_COND_SUFFIX@ -#cmakedefine SDL_THREAD_PTHREAD @SDL_THREAD_PTHREAD@ -#cmakedefine SDL_THREAD_PTHREAD_RECURSIVE_MUTEX @SDL_THREAD_PTHREAD_RECURSIVE_MUTEX@ -#cmakedefine SDL_THREAD_PTHREAD_RECURSIVE_MUTEX_NP @SDL_THREAD_PTHREAD_RECURSIVE_MUTEX_NP@ -#cmakedefine SDL_THREAD_WINDOWS @SDL_THREAD_WINDOWS@ -#cmakedefine SDL_THREAD_OS2 @SDL_THREAD_OS2@ -#cmakedefine SDL_THREAD_VITA @SDL_THREAD_VITA@ -#cmakedefine SDL_THREAD_PSP @SDL_THREAD_PSP@ -#cmakedefine SDL_THREAD_PS2 @SDL_THREAD_PS2@ -#cmakedefine SDL_THREAD_N3DS @SDL_THREAD_N3DS@ - -/* Enable various timer systems */ -#cmakedefine SDL_TIMER_HAIKU @SDL_TIMER_HAIKU@ -#cmakedefine SDL_TIMER_DUMMY @SDL_TIMER_DUMMY@ -#cmakedefine SDL_TIMER_UNIX @SDL_TIMER_UNIX@ -#cmakedefine SDL_TIMER_WINDOWS @SDL_TIMER_WINDOWS@ -#cmakedefine SDL_TIMER_OS2 @SDL_TIMER_OS2@ -#cmakedefine SDL_TIMER_VITA @SDL_TIMER_VITA@ -#cmakedefine SDL_TIMER_PSP @SDL_TIMER_PSP@ -#cmakedefine SDL_TIMER_PS2 @SDL_TIMER_PS2@ -#cmakedefine SDL_TIMER_N3DS @SDL_TIMER_N3DS@ - -/* Enable various video drivers */ -#cmakedefine SDL_VIDEO_DRIVER_ANDROID @SDL_VIDEO_DRIVER_ANDROID@ -#cmakedefine SDL_VIDEO_DRIVER_EMSCRIPTEN @SDL_VIDEO_DRIVER_EMSCRIPTEN@ -#cmakedefine SDL_VIDEO_DRIVER_HAIKU @SDL_VIDEO_DRIVER_HAIKU@ -#cmakedefine SDL_VIDEO_DRIVER_COCOA @SDL_VIDEO_DRIVER_COCOA@ -#cmakedefine SDL_VIDEO_DRIVER_UIKIT @SDL_VIDEO_DRIVER_UIKIT@ -#cmakedefine SDL_VIDEO_DRIVER_DIRECTFB @SDL_VIDEO_DRIVER_DIRECTFB@ -#cmakedefine SDL_VIDEO_DRIVER_DIRECTFB_DYNAMIC @SDL_VIDEO_DRIVER_DIRECTFB_DYNAMIC@ -#cmakedefine SDL_VIDEO_DRIVER_DUMMY @SDL_VIDEO_DRIVER_DUMMY@ -#cmakedefine SDL_VIDEO_DRIVER_OFFSCREEN @SDL_VIDEO_DRIVER_OFFSCREEN@ -#cmakedefine SDL_VIDEO_DRIVER_WINDOWS @SDL_VIDEO_DRIVER_WINDOWS@ -#cmakedefine SDL_VIDEO_DRIVER_WINRT @SDL_VIDEO_DRIVER_WINRT@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND @SDL_VIDEO_DRIVER_WAYLAND@ -#cmakedefine SDL_VIDEO_DRIVER_RPI @SDL_VIDEO_DRIVER_RPI@ -#cmakedefine SDL_VIDEO_DRIVER_VIVANTE @SDL_VIDEO_DRIVER_VIVANTE@ -#cmakedefine SDL_VIDEO_DRIVER_VIVANTE_VDK @SDL_VIDEO_DRIVER_VIVANTE_VDK@ -#cmakedefine SDL_VIDEO_DRIVER_OS2 @SDL_VIDEO_DRIVER_OS2@ -#cmakedefine SDL_VIDEO_DRIVER_QNX @SDL_VIDEO_DRIVER_QNX@ -#cmakedefine SDL_VIDEO_DRIVER_RISCOS @SDL_VIDEO_DRIVER_RISCOS@ -#cmakedefine SDL_VIDEO_DRIVER_PSP @SDL_VIDEO_DRIVER_PSP@ -#cmakedefine SDL_VIDEO_DRIVER_PS2 @SDL_VIDEO_DRIVER_PS2@ - -#cmakedefine SDL_VIDEO_DRIVER_KMSDRM @SDL_VIDEO_DRIVER_KMSDRM@ -#cmakedefine SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC @SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC@ -#cmakedefine SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC_GBM @SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC_GBM@ - -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_QT_TOUCH @SDL_VIDEO_DRIVER_WAYLAND_QT_TOUCH@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC @SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_EGL @SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_EGL@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_CURSOR @SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_CURSOR@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_XKBCOMMON @SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_XKBCOMMON@ -#cmakedefine SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_LIBDECOR @SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_LIBDECOR@ - -#cmakedefine SDL_VIDEO_DRIVER_X11 @SDL_VIDEO_DRIVER_X11@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC @SDL_VIDEO_DRIVER_X11_DYNAMIC@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT @SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XCURSOR @SDL_VIDEO_DRIVER_X11_DYNAMIC_XCURSOR@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 @SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XFIXES @SDL_VIDEO_DRIVER_X11_DYNAMIC_XFIXES@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR @SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR@ -#cmakedefine SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS @SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XCURSOR @SDL_VIDEO_DRIVER_X11_XCURSOR@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XDBE @SDL_VIDEO_DRIVER_X11_XDBE@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XINPUT2 @SDL_VIDEO_DRIVER_X11_XINPUT2@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XINPUT2_SUPPORTS_MULTITOUCH @SDL_VIDEO_DRIVER_X11_XINPUT2_SUPPORTS_MULTITOUCH@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XFIXES @SDL_VIDEO_DRIVER_X11_XFIXES@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XRANDR @SDL_VIDEO_DRIVER_X11_XRANDR@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XSCRNSAVER @SDL_VIDEO_DRIVER_X11_XSCRNSAVER@ -#cmakedefine SDL_VIDEO_DRIVER_X11_XSHAPE @SDL_VIDEO_DRIVER_X11_XSHAPE@ -#cmakedefine SDL_VIDEO_DRIVER_X11_SUPPORTS_GENERIC_EVENTS @SDL_VIDEO_DRIVER_X11_SUPPORTS_GENERIC_EVENTS@ -#cmakedefine SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM @SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM@ -#cmakedefine SDL_VIDEO_DRIVER_VITA @SDL_VIDEO_DRIVER_VITA@ -#cmakedefine SDL_VIDEO_DRIVER_N3DS @SDL_VIDEO_DRIVER_N3DS@ - -#cmakedefine SDL_VIDEO_RENDER_D3D @SDL_VIDEO_RENDER_D3D@ -#cmakedefine SDL_VIDEO_RENDER_D3D11 @SDL_VIDEO_RENDER_D3D11@ -#cmakedefine SDL_VIDEO_RENDER_D3D12 @SDL_VIDEO_RENDER_D3D12@ -#cmakedefine SDL_VIDEO_RENDER_OGL @SDL_VIDEO_RENDER_OGL@ -#cmakedefine SDL_VIDEO_RENDER_OGL_ES @SDL_VIDEO_RENDER_OGL_ES@ -#cmakedefine SDL_VIDEO_RENDER_OGL_ES2 @SDL_VIDEO_RENDER_OGL_ES2@ -#cmakedefine SDL_VIDEO_RENDER_DIRECTFB @SDL_VIDEO_RENDER_DIRECTFB@ -#cmakedefine SDL_VIDEO_RENDER_METAL @SDL_VIDEO_RENDER_METAL@ -#cmakedefine SDL_VIDEO_RENDER_VITA_GXM @SDL_VIDEO_RENDER_VITA_GXM@ -#cmakedefine SDL_VIDEO_RENDER_PS2 @SDL_VIDEO_RENDER_PS2@ -#cmakedefine SDL_VIDEO_RENDER_PSP @SDL_VIDEO_RENDER_PSP@ - -/* Enable OpenGL support */ -#cmakedefine SDL_VIDEO_OPENGL @SDL_VIDEO_OPENGL@ -#cmakedefine SDL_VIDEO_OPENGL_ES @SDL_VIDEO_OPENGL_ES@ -#cmakedefine SDL_VIDEO_OPENGL_ES2 @SDL_VIDEO_OPENGL_ES2@ -#cmakedefine SDL_VIDEO_OPENGL_BGL @SDL_VIDEO_OPENGL_BGL@ -#cmakedefine SDL_VIDEO_OPENGL_CGL @SDL_VIDEO_OPENGL_CGL@ -#cmakedefine SDL_VIDEO_OPENGL_GLX @SDL_VIDEO_OPENGL_GLX@ -#cmakedefine SDL_VIDEO_OPENGL_WGL @SDL_VIDEO_OPENGL_WGL@ -#cmakedefine SDL_VIDEO_OPENGL_EGL @SDL_VIDEO_OPENGL_EGL@ -#cmakedefine SDL_VIDEO_OPENGL_OSMESA @SDL_VIDEO_OPENGL_OSMESA@ -#cmakedefine SDL_VIDEO_OPENGL_OSMESA_DYNAMIC @SDL_VIDEO_OPENGL_OSMESA_DYNAMIC@ - -/* Enable Vulkan support */ -#cmakedefine SDL_VIDEO_VULKAN @SDL_VIDEO_VULKAN@ - -/* Enable Metal support */ -#cmakedefine SDL_VIDEO_METAL @SDL_VIDEO_METAL@ - -/* Enable system power support */ -#cmakedefine SDL_POWER_ANDROID @SDL_POWER_ANDROID@ -#cmakedefine SDL_POWER_LINUX @SDL_POWER_LINUX@ -#cmakedefine SDL_POWER_WINDOWS @SDL_POWER_WINDOWS@ -#cmakedefine SDL_POWER_WINRT @SDL_POWER_WINRT@ -#cmakedefine SDL_POWER_MACOSX @SDL_POWER_MACOSX@ -#cmakedefine SDL_POWER_UIKIT @SDL_POWER_UIKIT@ -#cmakedefine SDL_POWER_HAIKU @SDL_POWER_HAIKU@ -#cmakedefine SDL_POWER_EMSCRIPTEN @SDL_POWER_EMSCRIPTEN@ -#cmakedefine SDL_POWER_HARDWIRED @SDL_POWER_HARDWIRED@ -#cmakedefine SDL_POWER_VITA @SDL_POWER_VITA@ -#cmakedefine SDL_POWER_PSP @SDL_POWER_PSP@ -#cmakedefine SDL_POWER_N3DS @SDL_POWER_N3DS@ - -/* Enable system filesystem support */ -#cmakedefine SDL_FILESYSTEM_ANDROID @SDL_FILESYSTEM_ANDROID@ -#cmakedefine SDL_FILESYSTEM_HAIKU @SDL_FILESYSTEM_HAIKU@ -#cmakedefine SDL_FILESYSTEM_COCOA @SDL_FILESYSTEM_COCOA@ -#cmakedefine SDL_FILESYSTEM_DUMMY @SDL_FILESYSTEM_DUMMY@ -#cmakedefine SDL_FILESYSTEM_RISCOS @SDL_FILESYSTEM_RISCOS@ -#cmakedefine SDL_FILESYSTEM_UNIX @SDL_FILESYSTEM_UNIX@ -#cmakedefine SDL_FILESYSTEM_WINDOWS @SDL_FILESYSTEM_WINDOWS@ -#cmakedefine SDL_FILESYSTEM_EMSCRIPTEN @SDL_FILESYSTEM_EMSCRIPTEN@ -#cmakedefine SDL_FILESYSTEM_OS2 @SDL_FILESYSTEM_OS2@ -#cmakedefine SDL_FILESYSTEM_VITA @SDL_FILESYSTEM_VITA@ -#cmakedefine SDL_FILESYSTEM_PSP @SDL_FILESYSTEM_PSP@ -#cmakedefine SDL_FILESYSTEM_PS2 @SDL_FILESYSTEM_PS2@ -#cmakedefine SDL_FILESYSTEM_N3DS @SDL_FILESYSTEM_N3DS@ - -/* Enable misc subsystem */ -#cmakedefine SDL_MISC_DUMMY @SDL_MISC_DUMMY@ - -/* Enable locale subsystem */ -#cmakedefine SDL_LOCALE_DUMMY @SDL_LOCALE_DUMMY@ - -/* Enable assembly routines */ -#cmakedefine SDL_ALTIVEC_BLITTERS @SDL_ALTIVEC_BLITTERS@ -#cmakedefine SDL_ARM_SIMD_BLITTERS @SDL_ARM_SIMD_BLITTERS@ -#cmakedefine SDL_ARM_NEON_BLITTERS @SDL_ARM_NEON_BLITTERS@ - -/* Whether SDL_DYNAMIC_API needs dlopen */ -#cmakedefine DYNAPI_NEEDS_DLOPEN @DYNAPI_NEEDS_DLOPEN@ - -/* Enable dynamic libsamplerate support */ -#cmakedefine SDL_LIBSAMPLERATE_DYNAMIC @SDL_LIBSAMPLERATE_DYNAMIC@ - -/* Enable ime support */ -#cmakedefine SDL_USE_IME @SDL_USE_IME@ - -/* Platform specific definitions */ -#cmakedefine SDL_IPHONE_KEYBOARD @SDL_IPHONE_KEYBOARD@ -#cmakedefine SDL_IPHONE_LAUNCHSCREEN @SDL_IPHONE_LAUNCHSCREEN@ - -#cmakedefine SDL_VIDEO_VITA_PIB @SDL_VIDEO_VITA_PIB@ -#cmakedefine SDL_VIDEO_VITA_PVR @SDL_VIDEO_VITA_PVR@ -#cmakedefine SDL_VIDEO_VITA_PVR_OGL @SDL_VIDEO_VITA_PVR_OGL@ - -#cmakedefine SDL_HAVE_LIBDECOR_GET_MIN_MAX @SDL_HAVE_LIBDECOR_GET_MIN_MAX@ - -#if !defined(HAVE_STDINT_H) && !defined(_STDINT_H_) -/* Most everything except Visual Studio 2008 and earlier has stdint.h now */ -#if defined(_MSC_VER) && (_MSC_VER < 1600) -typedef signed __int8 int8_t; -typedef unsigned __int8 uint8_t; -typedef signed __int16 int16_t; -typedef unsigned __int16 uint16_t; -typedef signed __int32 int32_t; -typedef unsigned __int32 uint32_t; -typedef signed __int64 int64_t; -typedef unsigned __int64 uint64_t; -#ifndef _UINTPTR_T_DEFINED -#ifdef _WIN64 -typedef unsigned __int64 uintptr_t; -#else -typedef unsigned int uintptr_t; -#endif -#define _UINTPTR_T_DEFINED -#endif -#endif /* Visual Studio 2008 */ -#endif /* !_STDINT_H_ && !HAVE_STDINT_H */ - -#endif /* SDL_config_h_ */ diff --git a/sdl/include/SDL_config.h.in b/sdl/include/SDL_config.h.in deleted file mode 100644 index be9b395..0000000 --- a/sdl/include/SDL_config.h.in +++ /dev/null @@ -1,500 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_h_ -#define SDL_config_h_ - -/** - * \file SDL_config.h.in - * - * This is a set of defines to configure the SDL features - */ - -/* General platform specific identifiers */ -#include "SDL_platform.h" - -/* Make sure that this isn't included by Visual C++ */ -#ifdef _MSC_VER -#error You should run git checkout -f include/SDL_config.h -#endif - -/* C language features */ -#undef const -#undef inline -#undef volatile - -/* C datatypes */ -#if defined(__LP64__) || defined(_LP64) || defined(_WIN64) -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -#undef HAVE_GCC_ATOMICS -#undef HAVE_GCC_SYNC_LOCK_TEST_AND_SET - -/* Comment this if you want to build without any C library requirements */ -#undef HAVE_LIBC -#ifdef HAVE_LIBC - -/* Useful headers */ -#undef STDC_HEADERS -#undef HAVE_ALLOCA_H -#undef HAVE_CTYPE_H -#undef HAVE_FLOAT_H -#undef HAVE_ICONV_H -#undef HAVE_INTTYPES_H -#undef HAVE_LIMITS_H -#undef HAVE_MALLOC_H -#undef HAVE_MATH_H -#undef HAVE_MEMORY_H -#undef HAVE_SIGNAL_H -#undef HAVE_STDARG_H -#undef HAVE_STDINT_H -#undef HAVE_STDIO_H -#undef HAVE_STDLIB_H -#undef HAVE_STRINGS_H -#undef HAVE_STRING_H -#undef HAVE_SYS_TYPES_H -#undef HAVE_WCHAR_H -#undef HAVE_LINUX_INPUT_H -#undef HAVE_PTHREAD_NP_H -#undef HAVE_LIBUNWIND_H - -/* C library functions */ -#undef HAVE_DLOPEN -#undef HAVE_MALLOC -#undef HAVE_CALLOC -#undef HAVE_REALLOC -#undef HAVE_FREE -#undef HAVE_ALLOCA -#ifndef __WIN32__ /* Don't use C runtime versions of these on Windows */ -#undef HAVE_GETENV -#undef HAVE_SETENV -#undef HAVE_PUTENV -#undef HAVE_UNSETENV -#endif -#undef HAVE_QSORT -#undef HAVE_BSEARCH -#undef HAVE_ABS -#undef HAVE_BCOPY -#undef HAVE_MEMSET -#undef HAVE_MEMCPY -#undef HAVE_MEMMOVE -#undef HAVE_MEMCMP -#undef HAVE_WCSLEN -#undef HAVE_WCSLCPY -#undef HAVE_WCSLCAT -#undef HAVE__WCSDUP -#undef HAVE_WCSDUP -#undef HAVE_WCSSTR -#undef HAVE_WCSCMP -#undef HAVE_WCSNCMP -#undef HAVE_WCSCASECMP -#undef HAVE__WCSICMP -#undef HAVE_WCSNCASECMP -#undef HAVE__WCSNICMP -#undef HAVE_STRLEN -#undef HAVE_STRLCPY -#undef HAVE_STRLCAT -#undef HAVE__STRREV -#undef HAVE__STRUPR -#undef HAVE__STRLWR -#undef HAVE_INDEX -#undef HAVE_RINDEX -#undef HAVE_STRCHR -#undef HAVE_STRRCHR -#undef HAVE_STRSTR -#undef HAVE_STRTOK_R -#undef HAVE_ITOA -#undef HAVE__LTOA -#undef HAVE__UITOA -#undef HAVE__ULTOA -#undef HAVE_STRTOL -#undef HAVE_STRTOUL -#undef HAVE__I64TOA -#undef HAVE__UI64TOA -#undef HAVE_STRTOLL -#undef HAVE_STRTOULL -#undef HAVE_STRTOD -#undef HAVE_ATOI -#undef HAVE_ATOF -#undef HAVE_STRCMP -#undef HAVE_STRNCMP -#undef HAVE__STRICMP -#undef HAVE_STRCASECMP -#undef HAVE__STRNICMP -#undef HAVE_STRNCASECMP -#undef HAVE_STRCASESTR -#undef HAVE_SSCANF -#undef HAVE_VSSCANF -#undef HAVE_SNPRINTF -#undef HAVE_VSNPRINTF -#undef HAVE_M_PI -#undef HAVE_ACOS -#undef HAVE_ACOSF -#undef HAVE_ASIN -#undef HAVE_ASINF -#undef HAVE_ATAN -#undef HAVE_ATANF -#undef HAVE_ATAN2 -#undef HAVE_ATAN2F -#undef HAVE_CEIL -#undef HAVE_CEILF -#undef HAVE_COPYSIGN -#undef HAVE_COPYSIGNF -#undef HAVE_COS -#undef HAVE_COSF -#undef HAVE_EXP -#undef HAVE_EXPF -#undef HAVE_FABS -#undef HAVE_FABSF -#undef HAVE_FLOOR -#undef HAVE_FLOORF -#undef HAVE_FMOD -#undef HAVE_FMODF -#undef HAVE_LOG -#undef HAVE_LOGF -#undef HAVE_LOG10 -#undef HAVE_LOG10F -#undef HAVE_LROUND -#undef HAVE_LROUNDF -#undef HAVE_POW -#undef HAVE_POWF -#undef HAVE_ROUND -#undef HAVE_ROUNDF -#undef HAVE_SCALBN -#undef HAVE_SCALBNF -#undef HAVE_SIN -#undef HAVE_SINF -#undef HAVE_SQRT -#undef HAVE_SQRTF -#undef HAVE_TAN -#undef HAVE_TANF -#undef HAVE_TRUNC -#undef HAVE_TRUNCF -#undef HAVE_FOPEN64 -#undef HAVE_FSEEKO -#undef HAVE_FSEEKO64 -#undef HAVE_SIGACTION -#undef HAVE_SIGTIMEDWAIT -#undef HAVE_SA_SIGACTION -#undef HAVE_SETJMP -#undef HAVE_NANOSLEEP -#undef HAVE_SYSCONF -#undef HAVE_SYSCTLBYNAME -#undef HAVE_CLOCK_GETTIME -#undef HAVE_GETPAGESIZE -#undef HAVE_MPROTECT -#undef HAVE_ICONV -#undef SDL_USE_LIBICONV -#undef HAVE_PTHREAD_SETNAME_NP -#undef HAVE_PTHREAD_SET_NAME_NP -#undef HAVE_SEM_TIMEDWAIT -#undef HAVE_GETAUXVAL -#undef HAVE_ELF_AUX_INFO -#undef HAVE_POLL -#undef HAVE_MEMFD_CREATE -#undef HAVE_POSIX_FALLOCATE -#undef HAVE__EXIT - -#else - -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#define HAVE_STDINT_H 1 -#endif /* HAVE_LIBC */ - -#undef HAVE_O_CLOEXEC -#undef HAVE_ALTIVEC_H -#undef HAVE_DBUS_DBUS_H -#undef HAVE_FCITX -#undef HAVE_SYS_INOTIFY_H -#undef HAVE_INOTIFY_INIT -#undef HAVE_INOTIFY_INIT1 -#undef HAVE_INOTIFY -#undef HAVE_IBUS_IBUS_H -#undef HAVE_IMMINTRIN_H -#undef HAVE_LIBUDEV_H -#undef HAVE_LIBUSB -#undef HAVE_LIBSAMPLERATE_H -#undef HAVE_LIBDECOR_H -#undef HAVE_LSXINTRIN_H -#undef HAVE_LASXINTRIN_H - -#undef HAVE_DDRAW_H -#undef HAVE_DINPUT_H -#undef HAVE_DSOUND_H -#undef HAVE_DXGI_H -#undef HAVE_WINDOWS_GAMING_INPUT_H -#undef HAVE_XINPUT_H - -#undef HAVE_MMDEVICEAPI_H -#undef HAVE_AUDIOCLIENT_H -#undef HAVE_TPCSHRD_H -#undef HAVE_SENSORSAPI_H -#undef HAVE_ROAPI_H -#undef HAVE_SHELLSCALINGAPI_H - -/* SDL internal assertion support */ -#undef SDL_DEFAULT_ASSERT_LEVEL - -/* Allow disabling of core subsystems */ -#undef SDL_ATOMIC_DISABLED -#undef SDL_AUDIO_DISABLED -#undef SDL_CPUINFO_DISABLED -#undef SDL_EVENTS_DISABLED -#undef SDL_FILE_DISABLED -#undef SDL_JOYSTICK_DISABLED -#undef SDL_HAPTIC_DISABLED -#undef SDL_HIDAPI_DISABLED -#undef SDL_SENSOR_DISABLED -#undef SDL_LOADSO_DISABLED -#undef SDL_RENDER_DISABLED -#undef SDL_THREADS_DISABLED -#undef SDL_TIMERS_DISABLED -#undef SDL_VIDEO_DISABLED -#undef SDL_POWER_DISABLED -#undef SDL_FILESYSTEM_DISABLED -#undef SDL_LOCALE_DISABLED -#undef SDL_MISC_DISABLED - -/* Enable various audio drivers */ -#undef SDL_AUDIO_DRIVER_AAUDIO -#undef SDL_AUDIO_DRIVER_ALSA -#undef SDL_AUDIO_DRIVER_ALSA_DYNAMIC -#undef SDL_AUDIO_DRIVER_ANDROID -#undef SDL_AUDIO_DRIVER_ARTS -#undef SDL_AUDIO_DRIVER_ARTS_DYNAMIC -#undef SDL_AUDIO_DRIVER_COREAUDIO -#undef SDL_AUDIO_DRIVER_DISK -#undef SDL_AUDIO_DRIVER_DSOUND -#undef SDL_AUDIO_DRIVER_DUMMY -#undef SDL_AUDIO_DRIVER_EMSCRIPTEN -#undef SDL_AUDIO_DRIVER_ESD -#undef SDL_AUDIO_DRIVER_ESD_DYNAMIC -#undef SDL_AUDIO_DRIVER_FUSIONSOUND -#undef SDL_AUDIO_DRIVER_FUSIONSOUND_DYNAMIC -#undef SDL_AUDIO_DRIVER_HAIKU -#undef SDL_AUDIO_DRIVER_JACK -#undef SDL_AUDIO_DRIVER_JACK_DYNAMIC -#undef SDL_AUDIO_DRIVER_NACL -#undef SDL_AUDIO_DRIVER_NAS -#undef SDL_AUDIO_DRIVER_NAS_DYNAMIC -#undef SDL_AUDIO_DRIVER_NETBSD -#undef SDL_AUDIO_DRIVER_OPENSLES -#undef SDL_AUDIO_DRIVER_OSS -#undef SDL_AUDIO_DRIVER_PAUDIO -#undef SDL_AUDIO_DRIVER_PIPEWIRE -#undef SDL_AUDIO_DRIVER_PIPEWIRE_DYNAMIC -#undef SDL_AUDIO_DRIVER_PULSEAUDIO -#undef SDL_AUDIO_DRIVER_PULSEAUDIO_DYNAMIC -#undef SDL_AUDIO_DRIVER_QSA -#undef SDL_AUDIO_DRIVER_SNDIO -#undef SDL_AUDIO_DRIVER_SNDIO_DYNAMIC -#undef SDL_AUDIO_DRIVER_SUNAUDIO -#undef SDL_AUDIO_DRIVER_WASAPI -#undef SDL_AUDIO_DRIVER_WINMM -#undef SDL_AUDIO_DRIVER_OS2 - -/* Enable various input drivers */ -#undef SDL_INPUT_LINUXEV -#undef SDL_INPUT_FBSDKBIO -#undef SDL_INPUT_LINUXKD -#undef SDL_INPUT_WSCONS -#undef SDL_JOYSTICK_HAIKU -#undef SDL_JOYSTICK_DINPUT -#undef SDL_JOYSTICK_WGI -#undef SDL_JOYSTICK_XINPUT -#undef SDL_JOYSTICK_DUMMY -#undef SDL_JOYSTICK_IOKIT -#undef SDL_JOYSTICK_MFI -#undef SDL_JOYSTICK_LINUX -#undef SDL_JOYSTICK_ANDROID -#undef SDL_JOYSTICK_OS2 -#undef SDL_JOYSTICK_USBHID -#undef SDL_HAVE_MACHINE_JOYSTICK_H -#undef SDL_JOYSTICK_HIDAPI -#undef SDL_JOYSTICK_RAWINPUT -#undef SDL_JOYSTICK_EMSCRIPTEN -#undef SDL_JOYSTICK_VIRTUAL -#undef SDL_HAPTIC_DUMMY -#undef SDL_HAPTIC_ANDROID -#undef SDL_HAPTIC_LINUX -#undef SDL_HAPTIC_IOKIT -#undef SDL_HAPTIC_DINPUT -#undef SDL_HAPTIC_XINPUT - -/* Enable various sensor drivers */ -#undef SDL_SENSOR_ANDROID -#undef SDL_SENSOR_COREMOTION -#undef SDL_SENSOR_WINDOWS -#undef SDL_SENSOR_DUMMY - -/* Enable various shared object loading systems */ -#undef SDL_LOADSO_DLOPEN -#undef SDL_LOADSO_DUMMY -#undef SDL_LOADSO_LDG -#undef SDL_LOADSO_WINDOWS -#undef SDL_LOADSO_OS2 - -/* Enable various threading systems */ -#undef SDL_THREAD_GENERIC_COND_SUFFIX -#undef SDL_THREAD_PTHREAD -#undef SDL_THREAD_PTHREAD_RECURSIVE_MUTEX -#undef SDL_THREAD_PTHREAD_RECURSIVE_MUTEX_NP -#undef SDL_THREAD_WINDOWS -#undef SDL_THREAD_OS2 - -/* Enable various timer systems */ -#undef SDL_TIMER_HAIKU -#undef SDL_TIMER_DUMMY -#undef SDL_TIMER_UNIX -#undef SDL_TIMER_WINDOWS -#undef SDL_TIMER_OS2 - -/* Enable various video drivers */ -#undef SDL_VIDEO_DRIVER_HAIKU -#undef SDL_VIDEO_DRIVER_COCOA -#undef SDL_VIDEO_DRIVER_DIRECTFB -#undef SDL_VIDEO_DRIVER_DIRECTFB_DYNAMIC -#undef SDL_VIDEO_DRIVER_DUMMY -#undef SDL_VIDEO_DRIVER_WINDOWS -#undef SDL_VIDEO_DRIVER_WAYLAND -#undef SDL_VIDEO_DRIVER_WAYLAND_QT_TOUCH -#undef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC -#undef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_EGL -#undef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_CURSOR -#undef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_XKBCOMMON -#undef SDL_VIDEO_DRIVER_WAYLAND_DYNAMIC_LIBDECOR -#undef SDL_VIDEO_DRIVER_X11 -#undef SDL_VIDEO_DRIVER_RPI -#undef SDL_VIDEO_DRIVER_KMSDRM -#undef SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC -#undef SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC_GBM -#undef SDL_VIDEO_DRIVER_ANDROID -#undef SDL_VIDEO_DRIVER_EMSCRIPTEN -#undef SDL_VIDEO_DRIVER_OFFSCREEN -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XCURSOR -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XFIXES -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR -#undef SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS -#undef SDL_VIDEO_DRIVER_X11_XCURSOR -#undef SDL_VIDEO_DRIVER_X11_XDBE -#undef SDL_VIDEO_DRIVER_X11_XINPUT2 -#undef SDL_VIDEO_DRIVER_X11_XINPUT2_SUPPORTS_MULTITOUCH -#undef SDL_VIDEO_DRIVER_X11_XFIXES -#undef SDL_VIDEO_DRIVER_X11_XRANDR -#undef SDL_VIDEO_DRIVER_X11_XSCRNSAVER -#undef SDL_VIDEO_DRIVER_X11_XSHAPE -#undef SDL_VIDEO_DRIVER_X11_SUPPORTS_GENERIC_EVENTS -#undef SDL_VIDEO_DRIVER_X11_HAS_XKBKEYCODETOKEYSYM -#undef SDL_VIDEO_DRIVER_NACL -#undef SDL_VIDEO_DRIVER_VIVANTE -#undef SDL_VIDEO_DRIVER_VIVANTE_VDK -#undef SDL_VIDEO_DRIVER_OS2 -#undef SDL_VIDEO_DRIVER_QNX -#undef SDL_VIDEO_DRIVER_RISCOS - -#undef SDL_VIDEO_RENDER_D3D -#undef SDL_VIDEO_RENDER_D3D11 -#undef SDL_VIDEO_RENDER_D3D12 -#undef SDL_VIDEO_RENDER_OGL -#undef SDL_VIDEO_RENDER_OGL_ES -#undef SDL_VIDEO_RENDER_OGL_ES2 -#undef SDL_VIDEO_RENDER_DIRECTFB -#undef SDL_VIDEO_RENDER_METAL - -/* Enable OpenGL support */ -#undef SDL_VIDEO_OPENGL -#undef SDL_VIDEO_OPENGL_ES -#undef SDL_VIDEO_OPENGL_ES2 -#undef SDL_VIDEO_OPENGL_BGL -#undef SDL_VIDEO_OPENGL_CGL -#undef SDL_VIDEO_OPENGL_EGL -#undef SDL_VIDEO_OPENGL_GLX -#undef SDL_VIDEO_OPENGL_WGL -#undef SDL_VIDEO_OPENGL_OSMESA -#undef SDL_VIDEO_OPENGL_OSMESA_DYNAMIC - -/* Enable Vulkan support */ -#undef SDL_VIDEO_VULKAN - -/* Enable Metal support */ -#undef SDL_VIDEO_METAL - -/* Enable system power support */ -#undef SDL_POWER_LINUX -#undef SDL_POWER_WINDOWS -#undef SDL_POWER_MACOSX -#undef SDL_POWER_HAIKU -#undef SDL_POWER_ANDROID -#undef SDL_POWER_EMSCRIPTEN -#undef SDL_POWER_HARDWIRED - -/* Enable system filesystem support */ -#undef SDL_FILESYSTEM_ANDROID -#undef SDL_FILESYSTEM_HAIKU -#undef SDL_FILESYSTEM_COCOA -#undef SDL_FILESYSTEM_DUMMY -#undef SDL_FILESYSTEM_RISCOS -#undef SDL_FILESYSTEM_UNIX -#undef SDL_FILESYSTEM_WINDOWS -#undef SDL_FILESYSTEM_NACL -#undef SDL_FILESYSTEM_EMSCRIPTEN -#undef SDL_FILESYSTEM_OS2 -#undef SDL_FILESYSTEM_VITA -#undef SDL_FILESYSTEM_PSP -#undef SDL_FILESYSTEM_PS2 - -/* Enable misc subsystem */ -#undef SDL_MISC_DUMMY - -/* Enable locale subsystem */ -#undef SDL_LOCALE_DUMMY - -/* Enable assembly routines */ -#undef SDL_ALTIVEC_BLITTERS -#undef SDL_ARM_SIMD_BLITTERS -#undef SDL_ARM_NEON_BLITTERS - -/* Whether SDL_DYNAMIC_API needs dlopen() */ -#undef DYNAPI_NEEDS_DLOPEN - -/* Enable ime support */ -#undef SDL_USE_IME - -/* Enable dynamic udev support */ -#undef SDL_UDEV_DYNAMIC - -/* Enable dynamic libusb support */ -#undef SDL_LIBUSB_DYNAMIC - -/* Enable dynamic libsamplerate support */ -#undef SDL_LIBSAMPLERATE_DYNAMIC - -/* Libdecor get min/max content size functions */ -#undef SDL_HAVE_LIBDECOR_GET_MIN_MAX - -#endif /* SDL_config_h_ */ diff --git a/sdl/include/SDL_config_android.h b/sdl/include/SDL_config_android.h deleted file mode 100644 index f582f07..0000000 --- a/sdl/include/SDL_config_android.h +++ /dev/null @@ -1,194 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config_emscripten.h b/sdl/include/SDL_config_emscripten.h deleted file mode 100644 index e5e8fa4..0000000 --- a/sdl/include/SDL_config_emscripten.h +++ /dev/null @@ -1,218 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_emscripten_h_ -#define _SDL_config_emscripten_h_ - -#include "SDL_platform.h" - -/** - * \file SDL_config_emscripten.h - * - * This is a configuration that can be used to build SDL for Emscripten. - */ - -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif -#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_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_WCHAR_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_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 -#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_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 -#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_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_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 - -/* Enable various input drivers */ -#define SDL_JOYSTICK_EMSCRIPTEN 1 - -/* Enable various sensor drivers */ -#define SDL_SENSOR_DUMMY 1 - -/* 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 various timer systems */ -#define SDL_TIMER_UNIX 1 - -/* Enable various video drivers */ -#define SDL_VIDEO_DRIVER_EMSCRIPTEN 1 - -#define SDL_VIDEO_RENDER_OGL_ES2 1 - -/* Enable OpenGL support */ -/* #undef SDL_VIDEO_OPENGL */ -/* #undef SDL_VIDEO_OPENGL_ES */ -#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 */ - -/* Enable system power support */ -#define SDL_POWER_EMSCRIPTEN 1 - -/* Enable system filesystem support */ -#define SDL_FILESYSTEM_EMSCRIPTEN 1 - -#endif /* _SDL_config_emscripten_h_ */ diff --git a/sdl/include/SDL_config_iphoneos.h b/sdl/include/SDL_config_iphoneos.h deleted file mode 100644 index c4ae17a..0000000 --- a/sdl/include/SDL_config_iphoneos.h +++ /dev/null @@ -1,217 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_iphoneos_h_ -#define SDL_config_iphoneos_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -#ifdef __LP64__ -#define SIZEOF_VOIDP 8 -#else -#define SIZEOF_VOIDP 4 -#endif - -#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 -/* The libunwind functions are only available on x86 */ -/* #undef HAVE_LIBUNWIND_H */ - -/* 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_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_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_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 - -/* Enable the stub haptic driver (src/haptic/dummy/\*.c) */ -#define SDL_HAPTIC_DUMMY 1 - -/* Enable joystick support */ -/* 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 - -#ifdef __TVOS__ -#define SDL_SENSOR_DUMMY 1 -#else -/* Enable the CoreMotion sensor driver */ -#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 - -/* Enable various timer systems */ -#define SDL_TIMER_UNIX 1 - -/* Supported video drivers */ -#define SDL_VIDEO_DRIVER_UIKIT 1 -#define SDL_VIDEO_DRIVER_DUMMY 1 - -/* Enable OpenGL ES */ -#if !TARGET_OS_MACCATALYST -#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 -#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 -#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 -#endif - -#if SDL_PLATFORM_SUPPORTS_METAL -#define SDL_VIDEO_METAL 1 -#endif - -/* Enable system power support */ -#define SDL_POWER_UIKIT 1 - -/* enable iPhone keyboard support */ -#define SDL_IPHONE_KEYBOARD 1 - -/* enable iOS extended launch screen */ -#define SDL_IPHONE_LAUNCHSCREEN 1 - -/* enable filesystem support */ -#define SDL_FILESYSTEM_COCOA 1 - -#endif /* SDL_config_iphoneos_h_ */ diff --git a/sdl/include/SDL_config_macosx.h b/sdl/include/SDL_config_macosx.h deleted file mode 100644 index 04b6e10..0000000 --- a/sdl/include/SDL_config_macosx.h +++ /dev/null @@ -1,277 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_macosx_h_ -#define SDL_config_macosx_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* 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_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 -#define HAVE_LIBUNWIND_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_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_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_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_SYSCTLBYNAME 1 - -#if defined(__has_include) && (defined(__i386__) || defined(__x86_64)) -# if __has_include() -# define HAVE_IMMINTRIN_H 1 -# endif -#endif - -#if (MAC_OS_X_VERSION_MAX_ALLOWED >= 1070) -#define HAVE_O_CLOEXEC 1 -#endif - -#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 - -/* Enable various input drivers */ -#define SDL_JOYSTICK_HIDAPI 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 the dummy sensor driver */ -#define SDL_SENSOR_DUMMY 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_COCOA 1 -#define SDL_VIDEO_DRIVER_DUMMY 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" -#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 "/opt/X11/lib/libXi.6.dylib" -#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/opt/X11/lib/libXrandr.2.dylib" -#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS "/opt/X11/lib/libXss.1.dylib" -#define SDL_VIDEO_DRIVER_X11_XDBE 1 -#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 - -#ifdef MAC_OS_X_VERSION_10_8 -/* - * No matter the versions targeted, this is the 10.8 or later SDK, so you have - * to use the external Xquartz, which is a more modern Xlib. Previous SDKs - * used an older Xlib. - */ -#define SDL_VIDEO_DRIVER_X11_XINPUT2 1 -#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_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 -#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 -#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 - -/* 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 -#define SDL_VIDEO_METAL 1 -#else -#define SDL_VIDEO_METAL 0 -#endif -#endif - -/* Enable system power support */ -#define SDL_POWER_MACOSX 1 - -/* enable filesystem support */ -#define SDL_FILESYSTEM_COCOA 1 - -/* Enable assembly routines */ -#ifdef __ppc__ -#define SDL_ALTIVEC_BLITTERS 1 -#endif - -#endif /* SDL_config_macosx_h_ */ diff --git a/sdl/include/SDL_config_minimal.h b/sdl/include/SDL_config_minimal.h deleted file mode 100644 index 58c1058..0000000 --- a/sdl/include/SDL_config_minimal.h +++ /dev/null @@ -1,95 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_minimal_h_ -#define SDL_config_minimal_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/** - * \file SDL_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 - -#if !defined(HAVE_STDINT_H) && !defined(_STDINT_H_) -/* Most everything except Visual Studio 2008 and earlier has stdint.h now */ -#if defined(_MSC_VER) && (_MSC_VER < 1600) -typedef signed __int8 int8_t; -typedef unsigned __int8 uint8_t; -typedef signed __int16 int16_t; -typedef unsigned __int16 uint16_t; -typedef signed __int32 int32_t; -typedef unsigned __int32 uint32_t; -typedef signed __int64 int64_t; -typedef unsigned __int64 uint64_t; -#ifndef _UINTPTR_T_DEFINED -#ifdef _WIN64 -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 __GNUC__ -#define HAVE_GCC_SYNC_LOCK_TEST_AND_SET 1 -#endif - -/* 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 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 - -/* Enable the dummy video driver (src/video/dummy/\*.c) */ -#define SDL_VIDEO_DRIVER_DUMMY 1 - -/* Enable the dummy filesystem driver (src/filesystem/dummy/\*.c) */ -#define SDL_FILESYSTEM_DUMMY 1 - -#endif /* SDL_config_minimal_h_ */ diff --git a/sdl/include/SDL_config_ngage.h b/sdl/include/SDL_config_ngage.h deleted file mode 100644 index 95c13ff..0000000 --- a/sdl/include/SDL_config_ngage.h +++ /dev/null @@ -1,89 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config_os2.h b/sdl/include/SDL_config_os2.h deleted file mode 100644 index 25df8d0..0000000 --- a/sdl/include/SDL_config_os2.h +++ /dev/null @@ -1,204 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config_pandora.h b/sdl/include/SDL_config_pandora.h deleted file mode 100644 index 1b9ce0a..0000000 --- a/sdl/include/SDL_config_pandora.h +++ /dev/null @@ -1,141 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config_windows.h b/sdl/include/SDL_config_windows.h deleted file mode 100644 index 28b54b9..0000000 --- a/sdl/include/SDL_config_windows.h +++ /dev/null @@ -1,333 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_windows_h_ -#define SDL_config_windows_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* 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. - * If your compiler doesn't support __has_include() but you have winsdkver.h, define HAVE_WINSDKVER_H. */ -#if !defined(HAVE_WINSDKVER_H) && defined(__has_include) -#if __has_include() -#define HAVE_WINSDKVER_H 1 -#endif -#endif - -#ifdef HAVE_WINSDKVER_H -#include -#endif - -/* sdkddkver.h defines more specific SDK version numbers. This is needed because older versions of the - * Windows 10 SDK have broken declarations for the C API for DirectX 12. */ -#if !defined(HAVE_SDKDDKVER_H) && defined(__has_include) -#if __has_include() -#define HAVE_SDKDDKVER_H 1 -#endif -#endif - -#ifdef HAVE_SDKDDKVER_H -#include -#endif - -/* This is a set of defines to configure the SDL features */ - -#if !defined(HAVE_STDINT_H) && !defined(_STDINT_H_) -/* Most everything except Visual Studio 2008 and earlier has stdint.h now */ -#if defined(_MSC_VER) && (_MSC_VER < 1600) -typedef signed __int8 int8_t; -typedef unsigned __int8 uint8_t; -typedef signed __int16 int16_t; -typedef unsigned __int16 uint16_t; -typedef signed __int32 int32_t; -typedef unsigned __int32 uint32_t; -typedef signed __int64 int64_t; -typedef unsigned __int64 uint64_t; -#ifndef _UINTPTR_T_DEFINED -#ifdef _WIN64 -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 - -#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_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 -#define HAVE_MMDEVICEAPI_H 1 -#define HAVE_AUDIOCLIENT_H 1 -#define HAVE_TPCSHRD_H 1 -#define HAVE_SENSORSAPI_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 -# endif -#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_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 -/* 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 -#define HAVE_MEMMOVE 1 -#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 -/* #undef HAVE_STRTOK_R */ -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__LTOA */ -/* #undef HAVE__ULTOA */ -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 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__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_ATAN2F 1 -#define HAVE_CEILF 1 -#define HAVE__COPYSIGN 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_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#endif -#if defined(_MSC_VER) -/* These functions were added with the VC++ 2013 C runtime library */ -#if _MSC_VER >= 1800 -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_VSSCANF 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE_SCALBN 1 -#define HAVE_SCALBNF 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 -#else -#define HAVE_M_PI 1 -#endif -#else -#define HAVE_STDARG_H 1 -#define HAVE_STDDEF_H 1 -#endif - -/* 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 - -/* Enable various input drivers */ -#define SDL_JOYSTICK_DINPUT 1 -#define SDL_JOYSTICK_HIDAPI 1 -#ifndef __WINRT__ -#define SDL_JOYSTICK_RAWINPUT 1 -#endif -#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 - -/* Enable the sensor driver */ -#ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 -#else -#define SDL_SENSOR_DUMMY 1 -#endif - -/* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 - -/* Enable various threading systems */ -#define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 - -/* Enable various timer systems */ -#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 - -/* 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 - -/* Enable Vulkan support */ -#define SDL_VIDEO_VULKAN 1 - -/* Enable system power support */ -#define SDL_POWER_WINDOWS 1 - -/* Enable filesystem support */ -#define SDL_FILESYSTEM_WINDOWS 1 - -#endif /* SDL_config_windows_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/sdl/include/SDL_config_wingdk.h b/sdl/include/SDL_config_wingdk.h deleted file mode 100644 index 35ecfb4..0000000 --- a/sdl/include/SDL_config_wingdk.h +++ /dev/null @@ -1,253 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_wingdk_h_ -#define SDL_config_wingdk_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* 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 - -#define HAVE_DDRAW_H 1 -#define HAVE_DINPUT_H 1 -#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_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 -#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 -# endif -#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_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 -/* 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 -/* #undef HAVE_STRTOK_R */ -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__LTOA */ -/* #undef HAVE__ULTOA */ -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 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__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_ATAN2F 1 -#define HAVE_CEILF 1 -#define HAVE__COPYSIGN 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_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#if defined(_MSC_VER) -/* These functions were added with the VC++ 2013 C runtime library */ -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_VSSCANF 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE_SCALBN 1 -#define HAVE_SCALBNF 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 - -/* 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 - -/* 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 - -/* Enable the sensor driver */ -#ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 -#else -#define SDL_SENSOR_DUMMY 1 -#endif - -/* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 - -/* Enable various threading systems */ -#define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 - -/* Enable various timer systems */ -#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 - -/* 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 - -/* Enable Vulkan support */ -#define SDL_VIDEO_VULKAN 1 - -/* Enable system power support */ -#define SDL_POWER_WINDOWS 1 - -/* Enable filesystem support */ -#define SDL_FILESYSTEM_WINDOWS 1 - -#endif /* SDL_config_wingdk_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/sdl/include/SDL_config_winrt.h b/sdl/include/SDL_config_winrt.h deleted file mode 100644 index 1ee37ec..0000000 --- a/sdl/include/SDL_config_winrt.h +++ /dev/null @@ -1,220 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_config_xbox.h b/sdl/include/SDL_config_xbox.h deleted file mode 100644 index 47c4d5d..0000000 --- a/sdl/include/SDL_config_xbox.h +++ /dev/null @@ -1,240 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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_wingdk_h_ -#define SDL_config_wingdk_h_ -#define SDL_config_h_ - -#include "SDL_platform.h" - -/* 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 - -/*#define HAVE_DDRAW_H 1*/ -/*#define HAVE_DINPUT_H 1*/ -/*#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_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*/ -#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 -# endif -#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_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 -/* 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 -/* #undef HAVE_STRTOK_R */ -/* These functions have security warnings, so we won't use them */ -/* #undef HAVE__LTOA */ -/* #undef HAVE__ULTOA */ -#define HAVE_STRTOL 1 -#define HAVE_STRTOUL 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__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_ATAN2F 1 -#define HAVE_CEILF 1 -#define HAVE__COPYSIGN 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_LOG10F 1 -#define HAVE_POWF 1 -#define HAVE_SINF 1 -#define HAVE_SQRTF 1 -#define HAVE_TANF 1 -#if defined(_MSC_VER) -/* These functions were added with the VC++ 2013 C runtime library */ -#define HAVE_STRTOLL 1 -#define HAVE_STRTOULL 1 -#define HAVE_VSSCANF 1 -#define HAVE_LROUND 1 -#define HAVE_LROUNDF 1 -#define HAVE_ROUND 1 -#define HAVE_ROUNDF 1 -#define HAVE_SCALBN 1 -#define HAVE_SCALBNF 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 - -/* 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 - -/* 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 - -/* Enable the sensor driver */ -#ifdef HAVE_SENSORSAPI_H -#define SDL_SENSOR_WINDOWS 1 -#else -#define SDL_SENSOR_DUMMY 1 -#endif - -/* Enable various shared object loading systems */ -#define SDL_LOADSO_WINDOWS 1 - -/* Enable various threading systems */ -#define SDL_THREAD_GENERIC_COND_SUFFIX 1 -#define SDL_THREAD_WINDOWS 1 - -/* Enable various timer systems */ -#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 - -/* 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 - -/* Enable system power support */ -/*#define SDL_POWER_WINDOWS 1*/ -#define SDL_POWER_HARDWIRED 1 - -/* Enable filesystem support */ -/* #define SDL_FILESYSTEM_WINDOWS 1*/ -#define SDL_FILESYSTEM_XBOX 1 - -/* Disable IME as not supported yet (TODO: Xbox IME?) */ -#define SDL_DISABLE_WINDOWS_IME 1 - -#endif /* SDL_config_wingdk_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/sdl/include/SDL_cpuinfo.h b/sdl/include/SDL_cpuinfo.h deleted file mode 100644 index ce13eb5..0000000 --- a/sdl/include/SDL_cpuinfo.h +++ /dev/null @@ -1,603 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_endian.h b/sdl/include/SDL_endian.h deleted file mode 100644 index 057d6ec..0000000 --- a/sdl/include/SDL_endian.h +++ /dev/null @@ -1,396 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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. */ -#if defined(__clang__) && !_SDL_HAS_BUILTIN(_m_prefetch) -#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/sdl/include/SDL_error.h b/sdl/include/SDL_error.h deleted file mode 100644 index 45983f3..0000000 --- a/sdl/include/SDL_error.h +++ /dev/null @@ -1,163 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_events.h b/sdl/include/SDL_events.h deleted file mode 100644 index 1c8cf66..0000000 --- a/sdl/include/SDL_events.h +++ /dev/null @@ -1,1196 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_filesystem.h b/sdl/include/SDL_filesystem.h deleted file mode 100644 index a8eb754..0000000 --- a/sdl/include/SDL_filesystem.h +++ /dev/null @@ -1,149 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_gamecontroller.h b/sdl/include/SDL_gamecontroller.h deleted file mode 100644 index 952c89e..0000000 --- a/sdl/include/SDL_gamecontroller.h +++ /dev/null @@ -1,1110 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_gesture.h b/sdl/include/SDL_gesture.h deleted file mode 100644 index a71e2a4..0000000 --- a/sdl/include/SDL_gesture.h +++ /dev/null @@ -1,117 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_hidapi.h b/sdl/include/SDL_hidapi.h deleted file mode 100644 index f5a99a4..0000000 --- a/sdl/include/SDL_hidapi.h +++ /dev/null @@ -1,443 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_hints.h b/sdl/include/SDL_hints.h deleted file mode 100644 index 0996407..0000000 --- a/sdl/include/SDL_hints.h +++ /dev/null @@ -1,3334 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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 (the default) - * - "1": RAWINPUT drivers are used - */ -#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" - -/** - * Variable controlling the width of the PS2's framebuffer in pixels - * - * By default, this variable is "640" - */ -#define SDL_HINT_PS2_GS_WIDTH "SDL_PS2_GS_WIDTH" - -/** - * Variable controlling the height of the PS2's framebuffer in pixels - * - * By default, this variable is "448" - */ -#define SDL_HINT_PS2_GS_HEIGHT "SDL_PS2_GS_HEIGHT" - -/** - * Variable controlling whether the signal is interlaced or progressive - * - * - "0": Image is interlaced. (default) - * - "1": Image is progressive - */ -#define SDL_HINT_PS2_GS_PROGRESSIVE "SDL_PS2_GS_PROGRESSIVE" - -/** - * Variable controlling the video mode of the console - * - * - "": Console-native. (default) - * - "NTSC": 60hz region - * - "PAL": 50hz region - */ -#define SDL_HINT_PS2_GS_MODE "SDL_PS2_GS_MODE" - -/** - * 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/sdl/include/SDL_joystick.h b/sdl/include/SDL_joystick.h deleted file mode 100644 index a04e766..0000000 --- a/sdl/include/SDL_joystick.h +++ /dev/null @@ -1,1088 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_keyboard.h b/sdl/include/SDL_keyboard.h deleted file mode 100644 index be69fd8..0000000 --- a/sdl/include/SDL_keyboard.h +++ /dev/null @@ -1,361 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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 - see SDL_Keymod for details */ - 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/sdl/include/SDL_keycode.h b/sdl/include/SDL_keycode.h deleted file mode 100644 index e0ccf38..0000000 --- a/sdl/include/SDL_keycode.h +++ /dev/null @@ -1,358 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_log.h b/sdl/include/SDL_log.h deleted file mode 100644 index 9f29de2..0000000 --- a/sdl/include/SDL_log.h +++ /dev/null @@ -1,405 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_main.h b/sdl/include/SDL_main.h deleted file mode 100644 index acf4748..0000000 --- a/sdl/include/SDL_main.h +++ /dev/null @@ -1,282 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_mouse.h b/sdl/include/SDL_mouse.h deleted file mode 100644 index 366db41..0000000 --- a/sdl/include/SDL_mouse.h +++ /dev/null @@ -1,464 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_mutex.h b/sdl/include/SDL_mutex.h deleted file mode 100644 index 3934a91..0000000 --- a/sdl/include/SDL_mutex.h +++ /dev/null @@ -1,545 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_pixels.h b/sdl/include/SDL_pixels.h deleted file mode 100644 index 4481f0b..0000000 --- a/sdl/include/SDL_pixels.h +++ /dev/null @@ -1,686 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_platform.h b/sdl/include/SDL_platform.h deleted file mode 100644 index 36df782..0000000 --- a/sdl/include/SDL_platform.h +++ /dev/null @@ -1,275 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_quit.h b/sdl/include/SDL_quit.h deleted file mode 100644 index b66b13a..0000000 --- a/sdl/include/SDL_quit.h +++ /dev/null @@ -1,50 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_rect.h b/sdl/include/SDL_rect.h deleted file mode 100644 index 71dada6..0000000 --- a/sdl/include/SDL_rect.h +++ /dev/null @@ -1,376 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_render.h b/sdl/include/SDL_render.h deleted file mode 100644 index 3e56d55..0000000 --- a/sdl/include/SDL_render.h +++ /dev/null @@ -1,1932 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_revision.h b/sdl/include/SDL_revision.h deleted file mode 100644 index 36691f5..0000000 --- a/sdl/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/sdl/include/SDL_revision.h.cmake b/sdl/include/SDL_revision.h.cmake deleted file mode 100644 index 84e5f41..0000000 --- a/sdl/include/SDL_revision.h.cmake +++ /dev/null @@ -1,8 +0,0 @@ -#cmakedefine SDL_VENDOR_INFO "@SDL_VENDOR_INFO@" -#define SDL_REVISION_NUMBER 0 - -#ifdef SDL_VENDOR_INFO -#define SDL_REVISION "@SDL_REVISION@ (" SDL_VENDOR_INFO ")" -#else -#define SDL_REVISION "@SDL_REVISION@" -#endif diff --git a/sdl/include/SDL_rwops.h b/sdl/include/SDL_rwops.h deleted file mode 100644 index b1f62be..0000000 --- a/sdl/include/SDL_rwops.h +++ /dev/null @@ -1,844 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_shape.h b/sdl/include/SDL_shape.h deleted file mode 100644 index 56bf94c..0000000 --- a/sdl/include/SDL_shape.h +++ /dev/null @@ -1,155 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_stdinc.h b/sdl/include/SDL_stdinc.h deleted file mode 100644 index 211564a..0000000 --- a/sdl/include/SDL_stdinc.h +++ /dev/null @@ -1,874 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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) { - default: - 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/sdl/include/SDL_surface.h b/sdl/include/SDL_surface.h deleted file mode 100644 index 338d1b1..0000000 --- a/sdl/include/SDL_surface.h +++ /dev/null @@ -1,1001 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_system.h b/sdl/include/SDL_system.h deleted file mode 100644 index c6846d5..0000000 --- a/sdl/include/SDL_system.h +++ /dev/null @@ -1,642 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_syswm.h b/sdl/include/SDL_syswm.h deleted file mode 100644 index 67ed752..0000000 --- a/sdl/include/SDL_syswm.h +++ /dev/null @@ -1,386 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_test_images.h b/sdl/include/SDL_test_images.h deleted file mode 100644 index be41037..0000000 --- a/sdl/include/SDL_test_images.h +++ /dev/null @@ -1,78 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_test_random.h b/sdl/include/SDL_test_random.h deleted file mode 100644 index ce916ee..0000000 --- a/sdl/include/SDL_test_random.h +++ /dev/null @@ -1,115 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_thread.h b/sdl/include/SDL_thread.h deleted file mode 100644 index db67cd1..0000000 --- a/sdl/include/SDL_thread.h +++ /dev/null @@ -1,468 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_timer.h b/sdl/include/SDL_timer.h deleted file mode 100644 index 48929c7..0000000 --- a/sdl/include/SDL_timer.h +++ /dev/null @@ -1,222 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_touch.h b/sdl/include/SDL_touch.h deleted file mode 100644 index 93851de..0000000 --- a/sdl/include/SDL_touch.h +++ /dev/null @@ -1,150 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_types.h b/sdl/include/SDL_types.h deleted file mode 100644 index dadb1ec..0000000 --- a/sdl/include/SDL_types.h +++ /dev/null @@ -1,24 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_version.h b/sdl/include/SDL_version.h deleted file mode 100644 index f6d0b00..0000000 --- a/sdl/include/SDL_version.h +++ /dev/null @@ -1,205 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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 11 - -/** - * 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/sdl/include/SDL_video.h b/sdl/include/SDL_video.h deleted file mode 100644 index 9ab22b3..0000000 --- a/sdl/include/SDL_video.h +++ /dev/null @@ -1,2228 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/include/SDL_vulkan.h b/sdl/include/SDL_vulkan.h deleted file mode 100644 index e005ed3..0000000 --- a/sdl/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/sdl/include/begin_code.h b/sdl/include/begin_code.h deleted file mode 100644 index 9090ec2..0000000 --- a/sdl/include/begin_code.h +++ /dev/null @@ -1,189 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2026 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/sdl/lib/arm-macos/libSDL2.a b/sdl/lib/arm-macos/libSDL2.a deleted file mode 100644 index e2217b0..0000000 Binary files a/sdl/lib/arm-macos/libSDL2.a and /dev/null differ diff --git a/sdl/lib/x86_64-win/SDL2.lib b/sdl/lib/x86_64-win/SDL2.lib deleted file mode 100644 index 2c7dd22..0000000 Binary files a/sdl/lib/x86_64-win/SDL2.lib and /dev/null differ diff --git a/sdl_handmade.c b/sdl_handmade.c index d931c15..b401cd2 100644 --- a/sdl_handmade.c +++ b/sdl_handmade.c @@ -1,13 +1,16 @@ -#include "core.h" - +/* TODO: Does SDL3 still need this? */ #if OS_WINDOWS /* Remove SDL's entry point. */ #define SDL_MAIN_HANDLED #endif +#include "config.h" + +#include "helpers.h" + #include "handmade.h" #include "sdl_handmade.h" -#include +#include #include /* malloc, calloc */ #include /* memset, memcpy */ @@ -45,21 +48,21 @@ #define RESOLUTION_WIDTH 960 #define RESOLUTION_HEIGHT 540 -static int GlobalRunning; +static int global_running; -static unsigned long long GlobalPerfCountFrequency; +static unsigned long long global_perf_count_frequency; #define CONTROLLER_LEFT_THUMB_DEADZONE 8000 #define MAX_CONTROLLERS 4 -SDL_GameController *ControllerHandles[MAX_CONTROLLERS]; +SDL_Gamepad *controller_handles[MAX_CONTROLLERS]; -static struct offscreen_buffer GlobalBackbuffer; +static struct offscreen_buffer global_backbuffer; -SDL_Window *LastWindow; +SDL_Window *last_window; -static int IsFullscreen; -static struct sdl_window_size WindowSize; -static struct sdl_window_position WindowPosition; +static int is_full_screen; +static struct sdl_window_size window_size; +static struct sdl_window_position window_position; static int str_len(char *str) { @@ -69,538 +72,562 @@ static int str_len(char *str) return count; } -static unsigned int SafeTruncateUInt64(unsigned long long Value) +static unsigned int safe_truncate_uint64(unsigned long long value) { - unsigned int Result; + unsigned int result; - ASSERT(Value <= 0xFFFFFFFF); + assert(value <= 0xFFFFFFFF); - Result = (unsigned int)Value; + result = (unsigned int)value; - return Result; + return result; } struct debug_read_file_result -DEBUGPlatformReadEntireFile(struct thread_context *Thread, - const char *Filename) +debug_platform_read_entire_file(struct thread_context *thread, + const char *file_name) { - struct debug_read_file_result Result; + struct debug_read_file_result result; - SDL_RWops *FileHandle; + SDL_IOStream *f; - memset(&Result, 0, sizeof(Result)); + memset(&result, 0, sizeof(result)); - FileHandle = SDL_RWFromFile(Filename, "r"); - if(FileHandle) { - long long FileSize; - unsigned int ObjectsRead; + f = SDL_IOFromFile(file_name, "r"); + if(f) { + long long f_size; - FileSize = SDL_RWsize(FileHandle); + unsigned int bytes_read; - if(FileSize >= 0) { - Result.ContentsSize = SafeTruncateUInt64(FileSize); + f_size = SDL_GetIOSize(f); + if(f_size >= 0) { + result.contents_size = safe_truncate_uint64(f_size); } else { - Result.ContentsSize = 0; - SDL_RWclose(FileHandle); - return Result; + result.contents_size = 0; + SDL_CloseIO(f); + return result; } - Result.Contents = malloc(Result.ContentsSize); - if(!Result.Contents) { - Result.ContentsSize = 0; - SDL_RWclose(FileHandle); - return Result; + result.contents = malloc(result.contents_size); + if(!result.contents) { + result.contents_size = 0; + SDL_CloseIO(f); + return result; } - ObjectsRead = SDL_RWread(FileHandle, - (void *)Result.Contents, Result.ContentsSize, 1); - if(ObjectsRead == 0) { - free(Result.Contents); - Result.Contents = 0; - Result.ContentsSize = 0; - SDL_RWclose(FileHandle); - return Result; + while(f_size > 0) { + bytes_read = SDL_ReadIO(f, (void *)result.contents, f_size); + if(bytes_read == 0) { + result.contents_size = 0; + SDL_CloseIO(f); + return result; + } + f_size -= bytes_read; } - - SDL_RWclose(FileHandle); } - return Result; + return result; } -int DEBUGPlatformWriteEntireFile(struct thread_context *Thread, - const char *Filename, - unsigned int MemorySize, void *Memory) +int debug_platform_write_entire_file(struct thread_context *thread, + const char *file_name, + unsigned int memory_size, void *memory) { - SDL_RWops *FileHandle = SDL_RWFromFile(Filename, "w"); - if(FileHandle) { - unsigned int ObjectsWritten = SDL_RWwrite(FileHandle, - (void *)Memory, (unsigned int)MemorySize, 1); - if(ObjectsWritten == 0) { - SDL_RWclose(FileHandle); + SDL_IOStream *f; + + f = SDL_IOFromFile(file_name, "w"); + if(f) { + unsigned int bytes_written; + + bytes_written = SDL_WriteIO(f, memory, memory_size); + if(bytes_written < memory_size) { + SDL_CloseIO(f); return 0; } - SDL_RWclose(FileHandle); + SDL_CloseIO(f); return 1; } return 0; } -void DEBUGPlatformFreeFileMemory(struct thread_context *Thread, void *Memory) +void debug_platform_free_file_memory(struct thread_context *Thread, + void *memory) { - if(Memory) - free(Memory); + if(memory) + free(memory); } -void SetProgramIcon(struct game_offscreen_buffer *ProgramIcon) +void SetProgramIcon(struct game_offscreen_buffer *program_icon) { - SDL_Window *Window = LastWindow; + SDL_Window *window = last_window; - SDL_Surface *Icon = - SDL_CreateRGBSurfaceWithFormatFrom((void *)ProgramIcon->Memory, - ProgramIcon->Width, ProgramIcon->Height, - ProgramIcon->BytesPerPixel * 8, - ProgramIcon->BytesPerPixel * ProgramIcon->Width, - SDL_PIXELFORMAT_ARGB8888); - if(!Icon) { + SDL_Surface *icon = + SDL_CreateSurfaceFrom(program_icon->width, program_icon->height, + SDL_PIXELFORMAT_ARGB8888, + (void *)program_icon->memory, + program_icon->bytes_per_pixel * + program_icon->width); + if(!icon) { /* TODO: This didn't work . . . SDL_GetError() */ return ; } - SDL_SetWindowIcon(Window, Icon); - SDL_FreeSurface(Icon); + SDL_SetWindowIcon(window, icon); + SDL_DestroySurface(icon); } -static struct sdl_border_size SDLGetWindowBorderSizes(SDL_Window *Window) +static struct sdl_border_size +sdl_get_window_border_sizes(SDL_Window *window) { - struct sdl_border_size Result; - SDL_GetWindowBordersSize(Window, &Result.Top, &Result.Left, - &Result.Bottom, &Result.Right); - return Result; + struct sdl_border_size result; + SDL_GetWindowBordersSize(window, &result.top, &result.left, + &result.bottom, &result.right); + return result; } /* NOTE: All SDL window functions (SDL_GetWindowSize, SDL_GetWindowPosition, * SDL_SetWindowPosition, SDL_SetWindowSize) work ONLY with client area. */ -static struct sdl_window_size SDLGetBorderedWindowSize(SDL_Window *Window) +static struct sdl_window_size +sdl_get_bordered_window_size(SDL_Window *window) { - struct sdl_border_size Border = SDLGetWindowBorderSizes(Window); + struct sdl_border_size border = sdl_get_window_border_sizes(window); - struct sdl_window_size Dimension; - SDL_GetWindowSize(Window, &Dimension.Width, &Dimension.Height); + struct sdl_window_size dimension; + SDL_GetWindowSize(window, &dimension.width, &dimension.height); #if OS_WINDOWS - // On Windows, borders must be added. - Dimension.Height += Border.Top + Border.Bottom; + /* TODO: Check if this is still dysfunctional/inconsistent in SDL3. */ + /* On Windows, borders must be added. */ + dimension.Height += border.Top + border.Bottom; #endif - // Dimension.Width += Border.Left + Border.Right; + /* dimension.Width += border.Left + border.Right; */ - return Dimension; + return dimension; } static struct sdl_window_position -SDLGetBorderedWindowPosition(SDL_Window *Window) +sdl_get_bordered_window_position(SDL_Window *window) { - struct sdl_border_size Border = SDLGetWindowBorderSizes(Window); + struct sdl_border_size border = sdl_get_window_border_sizes(window); - struct sdl_window_position Position; - SDL_GetWindowPosition(Window, &Position.X, &Position.Y); - // Position.X -= Border.Left; - Position.Y -= Border.Top; + struct sdl_window_position position; + SDL_GetWindowPosition(window, &position.x, &position.y); + /* position.X -= border.Left; */ + position.y -= border.top; - return Position; -} - -static void SDLSetBorderedWindowPosition(SDL_Window *Window, int X, int Y) -{ - struct sdl_border_size Border = SDLGetWindowBorderSizes(Window); - - SDL_SetWindowPosition(Window, X, Y + Border.Top); + return position; } static void -SDLSetBorderedWindowSize(SDL_Window *Window, int Width, int Height) +sdl_set_bordered_window_position(SDL_Window *window, int x, int y) { - struct sdl_border_size Border = SDLGetWindowBorderSizes(Window); + struct sdl_border_size border = sdl_get_window_border_sizes(window); - /* SDL_SetWindowSize(Window, - Width - (Border.Left + Border.Right), - Height - (Border.Top + Border.Bottom)); */ - SDL_SetWindowSize(Window, Width, Height - (Border.Top + Border.Bottom)); + SDL_SetWindowPosition(window, x, y + border.top); } static void -SDLResizeTexture(struct offscreen_buffer *Buffer, - SDL_Renderer *Renderer, int Width, int Height) +sdl_set_bordered_window_size(SDL_Window *window, int width, int height) { - int BytesPerPixel; + struct sdl_border_size border = sdl_get_window_border_sizes(window); - if(Buffer->Texture) - SDL_DestroyTexture(Buffer->Texture); + /* SDL_SetWindowSize(window, + width - (border.Left + border.Right), + height - (border.Top + border.Bottom)); */ + SDL_SetWindowSize(window, width, height - (border.top + border.bottom)); +} - if(Buffer->Memory) - free(Buffer->Memory); +static void +sdl_resize_texture(struct offscreen_buffer *buffer, + SDL_Renderer *renderer, int width, int height) +{ + int bytes_per_pixel; - BytesPerPixel = 4; + if(buffer->texture) + SDL_DestroyTexture(buffer->texture); - Buffer->Texture = SDL_CreateTexture(Renderer, + if(buffer->memory) + free(buffer->memory); + + bytes_per_pixel = 4; + + buffer->texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STREAMING, - Width, Height); - Buffer->Memory = malloc(Width * Height * BytesPerPixel); + width, height); + buffer->memory = malloc(width * height * bytes_per_pixel); - Buffer->Height = Height; - Buffer->Width = Width; - Buffer->Pitch = Width * BytesPerPixel; + buffer->height = height; + buffer->width = width; + buffer->pitch = width * bytes_per_pixel; } -static void SDLDisplayBufferInWindow(struct offscreen_buffer *Buffer, - SDL_Window *Window, - SDL_Renderer *Renderer) +static void sdl_display_buffer_in_window(struct offscreen_buffer *buffer, + SDL_Window *window, + SDL_Renderer *renderer) { - int OffsetX, OffsetY; + int offset_x, offset_y; - struct sdl_window_size WinSize; + struct sdl_window_size win_size; - OffsetX = 10; - OffsetY = 10; + offset_x = 10; + offset_y = 10; - SDL_SetRenderDrawColor(Renderer, 0, 0, 0, 255); - SDL_RenderClear(Renderer); + SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255); + SDL_RenderClear(renderer); - if(SDL_UpdateTexture(Buffer->Texture, 0, Buffer->Memory, Buffer->Pitch)) { + if(SDL_UpdateTexture(buffer->texture, 0, buffer->memory, buffer->pitch)) { /* TODO: Do something about this error! */ } /* TODO: We temporarily introduce the target rectangle to avoid * stretching the canvas. */ /* SDL_RenderCopy(Renderer, Buffer.Texture, 0, 0); */ - WinSize = SDLGetBorderedWindowSize(Window); - if(WinSize.Width >= Buffer->Width*2 && - WinSize.Height >= Buffer->Height*2) + win_size = sdl_get_bordered_window_size(window); + if(win_size.width >= buffer->width*2 && + win_size.height >= buffer->height*2) { - SDL_Rect dest_rect; - dest_rect.x = OffsetX; - dest_rect.y = OffsetY; - dest_rect.w = Buffer->Width*2; - dest_rect.h = Buffer->Height*2; - SDL_RenderCopy(Renderer, Buffer->Texture, 0, - (const SDL_Rect *)(&dest_rect)); + SDL_FRect dest_rect; + dest_rect.x = (float)offset_x; + dest_rect.y = (float)offset_y; + dest_rect.w = (float)(buffer->width*2); + dest_rect.h = (float)(buffer->height*2); + SDL_RenderTexture(renderer, buffer->texture, + 0, (const SDL_FRect *)(&dest_rect)); } else { - SDL_Rect dest_rect; - dest_rect.x = OffsetX; - dest_rect.y = OffsetY; - dest_rect.w = RESOLUTION_WIDTH; - dest_rect.h = RESOLUTION_HEIGHT; - SDL_RenderCopy(Renderer, Buffer->Texture, 0, - (const SDL_Rect *)(&dest_rect)); + SDL_FRect dest_rect; + dest_rect.x = (float)offset_x; + dest_rect.y = (float)offset_y; + dest_rect.w = (float)RESOLUTION_WIDTH; + dest_rect.h = (float)RESOLUTION_HEIGHT; + SDL_RenderTexture(renderer, buffer->texture, + 0, (const SDL_FRect *)(&dest_rect)); } - SDL_RenderPresent(Renderer); + SDL_RenderPresent(renderer); } -static void SDLInitControllers() +static void sdl_init_controllers() { - int MaxJoysticks = SDL_NumJoysticks(); - int ControllerIndex = 0; + int max_joysticks, controller_index; - int JoystickIndex; - for(JoystickIndex = 0; JoystickIndex < MaxJoysticks; JoystickIndex++) + SDL_JoystickID *gamepads; + + int joystick_index; + + controller_index = 0; + + gamepads = SDL_GetJoysticks(&max_joysticks); + + /* TODO: Why would we fetch this by instance? Can we fetch available + * ones? */ + for(joystick_index = 0; + joystick_index < max_joysticks; + joystick_index++) { - if(!SDL_IsGameController(JoystickIndex)) + if(!SDL_IsGamepad(gamepads[joystick_index])) continue; - if(ControllerIndex >= MAX_CONTROLLERS) + if(controller_index >= MAX_CONTROLLERS) break; - ControllerHandles[ControllerIndex] = - SDL_GameControllerOpen(JoystickIndex); - ControllerIndex++; + controller_handles[controller_index] = + SDL_OpenGamepad(gamepads[joystick_index]); + controller_index++; } } /* -static void SDLDeinitControllers() +static void sdl_deinit_controllers() { - for(int ControllerIndex = 0; - ControllerIndex < MAX_CONTROLLERS; - ControllerIndex++) + int controller_index; + + for(controller_index = 0; + controller_index < MAX_CONTROLLERS; + controller_index++) { - if(ControllerHandles[ControllerIndex]) - SDL_GameControllerClose(ControllerHandles[ControllerIndex]); + if(controller_handles[controller_index]) + SDL_GameControllerClose(controller_handles[controller_index]); } } */ -static void SDLInitSound(int SamplesPerSecond, int BufferSize) +#if 0 +static void sdl_init_sound(int samples_per_second, int buffer_size) { - SDL_AudioSpec AudioSettings; - memset(&AudioSettings, 0, sizeof(AudioSettings)); + SDL_AudioSpec audio_settings; + memset(&audio_settings, 0, sizeof(audio_settings)); - AudioSettings.freq = SamplesPerSecond; - AudioSettings.format = AUDIO_S16LSB; - AudioSettings.channels = 2; + audio_settings.freq = samples_per_second; + audio_settings.format = SDL_AUDIO_S16LE; + audio_settings.channels = 2; /* TODO: Unsafe truncate from S32 to U16 */ - AudioSettings.samples = (unsigned short)BufferSize; + audio_settings.samples = (unsigned short)buffer_size; - SDL_OpenAudio(&AudioSettings, 0); + SDL_OpenAudio(&audio_settings, 0); - if(AudioSettings.format != AUDIO_S16LSB) { + if(audio_settings.format != AUDIO_S16LSB) { SDL_CloseAudio(); } } +#endif +#if 0 static void -SDLFillSoundBuffer(struct sdl_sound_output *SoundOutput, int BytesToWrite) +sdl_fill_sound_buffer(struct sdl_sound_output *sound_output, + int bytes_to_write) { - SDL_QueueAudio(1, SoundOutput->Samples, BytesToWrite); + SDL_QueueAudio(1, sound_output->Samples, bytes_to_write); } -static void SDLClearSoundBuffer(struct sdl_sound_output *SoundOutput) +static void sdl_clear_sound_buffer(struct sdl_sound_output *sound_output) { - memset(SoundOutput->Samples, 0, SoundOutput->SecondaryBufferSize); + memset(sound_output->Samples, 0, sound_output->SecondaryBufferSize); } +#endif static void -SDLProcessKeyboardMessage(struct game_button_state *NewState, int IsDown) +sdl_process_keyboard_message(struct game_button_state *new_state, + int is_down) { - if(NewState->EndedDown != IsDown) { - NewState->EndedDown = IsDown; - ++NewState->HalfTransitionCount; + if(new_state->ended_down != is_down) { + new_state->ended_down = is_down; + ++new_state->half_transition_count; } } -static void SDLProcessInputDigitalButton(SDL_GameController *Controller, - struct game_button_state *OldState, - SDL_GameControllerButton Button, - struct game_button_state *NewState) +static void sdl_process_input_digital_button(SDL_Gamepad *controller, + struct game_button_state *old_state, + SDL_GamepadButton button, + struct game_button_state *new_state) { - NewState->EndedDown = - SDL_GameControllerGetButton(Controller, Button); - NewState->HalfTransitionCount = - (OldState->EndedDown != NewState->EndedDown) ? 1 : 0; + new_state->ended_down = + SDL_GetGamepadButton(controller, button); + new_state->half_transition_count = + (old_state->ended_down != new_state->ended_down) ? 1 : 0; } -static void HandleEvent(SDL_Event *Event) +static void HandleEvent(SDL_Event *event) { - SDL_Window *Window = SDL_GetWindowFromID(Event->window.windowID); - SDL_Renderer *Renderer = SDL_GetRenderer(Window); + SDL_Window *window = SDL_GetWindowFromID(event->window.windowID); + SDL_Renderer *renderer = SDL_GetRenderer(window); - switch(Event->type) { - case SDL_QUIT: { - GlobalRunning = 0; + switch(event->type) { + case SDL_EVENT_QUIT: { + global_running = 0; } break; - case SDL_WINDOWEVENT: { - switch(Event->window.event) { - /* TODO: We temporarily disable for ease of writing the - * rendering code. */ + /* TODO: We temporarily disable for ease of writing the + * rendering code. */ #if 0 - /* TODO: For now we fix the width and height. */ - case SDL_WINDOWEVENT_SIZE_CHANGED: { - sdl_window_dimension Dimension = - SDLGetWindowDimension(Window); - SDLResizeTexture(&GlobalBackbuffer, Renderer, - Dimension.Width, Dimension.Height); - } break; + /* TODO: For now we fix the width and height. */ + case SDL_EVENT_WINDOW_RESIZED: { + sdl_window_dimension dimension = + SDLGetWindowDimension(window); + SDLResizeTexture(&global_backbuffer, renderer, + dimension.width, dimension.height); + } break; #endif - case SDL_WINDOWEVENT_EXPOSED: { - } break; + case SDL_EVENT_WINDOW_EXPOSED: { + } break; #if 0 - case SDL_WINDOWEVENT_FOCUS_GAINED: { - if(SDL_SetWindowOpacity(Window, 1.0f) != 0) { - /* TODO: This didn't work . . . SDL_GetError() */ - } - } break; - - case SDL_WINDOWEVENT_FOCUS_LOST: { - if(SDL_SetWindowOpacity(Window, 0.1f) != 0) { - /* TODO: This didn't work . . . SDL_GetError() */ - } - } break; -#endif + case SDL_EVENT_WINDOW_FOCUS_GAINED: { + if(SDL_SetWindowOpacity(window, 1.0f) != 0) { + /* TODO: This didn't work . . . SDL_GetError() */ } } break; + + case SDL_EVENT_WINDOW_FOCUS_LOST: { + if(SDL_SetWindowOpacity(window, 0.1f) != 0) { + /* TODO: This didn't work . . . SDL_GetError() */ + } + } break; +#endif } } -static void SDLToggleFullscreen(SDL_Window *Window) +static void sdl_toggle_fullscreen(SDL_Window *window) { - int err; + bool ok; - if(IsFullscreen) { - err = SDL_SetWindowFullscreen(Window, 0); - if(err == 0) { - SDLSetBorderedWindowSize(Window, - WindowSize.Width, - WindowSize.Height); - SDLSetBorderedWindowPosition(Window, - WindowPosition.X, - WindowPosition.Y); + if(is_full_screen) { + ok = SDL_SetWindowFullscreen(window, false); + if(ok) { + sdl_set_bordered_window_size(window, + window_size.width, + window_size.height); + sdl_set_bordered_window_position(window, + window_position.x, + window_position.y); - IsFullscreen = 0; + is_full_screen = 0; } else { /* TODO: This didn't work . . . SDL_GetError() */ } } else { - WindowSize = SDLGetBorderedWindowSize(Window); - WindowPosition = SDLGetBorderedWindowPosition(Window); + window_size = sdl_get_bordered_window_size(window); + window_position = sdl_get_bordered_window_position(window); - err = SDL_SetWindowFullscreen(Window, - SDL_WINDOW_FULLSCREEN_DESKTOP); - if(err == 0) { - IsFullscreen = 1; + ok = SDL_SetWindowFullscreen(window, true); + if(ok) { + is_full_screen = 1; } else { /* TODO: This didn't work . . . SDL_GetError() */ } } } -static void SDLProcessMessages(struct sdl_state *SDLState, - struct game_controller_input *KeyboardController) +static void sdl_process_messages(struct sdl_state *sdl_state, + struct game_controller_input *keyboard_controller) { - SDL_Event Event; - while(SDL_PollEvent(&Event)) { - SDL_Window *Window = SDL_GetWindowFromID(Event.window.windowID); - SDL_Renderer *Renderer = SDL_GetRenderer(Window); + SDL_Event event; + while(SDL_PollEvent(&event)) { + SDL_Window *window = SDL_GetWindowFromID(event.window.windowID); + SDL_Renderer *renderer = SDL_GetRenderer(window); - switch(Event.type) { - case SDL_KEYDOWN: - case SDL_KEYUP: { - SDL_Keycode KeyCode; - int IsDown, WasDown; + switch(event.type) { + case SDL_EVENT_KEY_DOWN: + case SDL_EVENT_KEY_UP: { + SDL_Keycode key_code; + int is_down, was_down; - KeyCode = Event.key.keysym.sym; - IsDown = (Event.key.state == SDL_PRESSED); - WasDown = 0; - if(Event.key.state == SDL_RELEASED) { - WasDown = 1; - } else if(Event.key.repeat != 0) { - WasDown = 1; + key_code = event.key.key; + is_down = event.key.down; + was_down = 0; + if(!event.key.down) { + was_down = 1; + } else if(event.key.repeat != 0) { + was_down = 1; } - if(Event.key.repeat == 0) { - if(KeyCode == SDLK_w) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.MoveUp, IsDown); - } else if(KeyCode == SDLK_s) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.MoveDown, IsDown); - } else if(KeyCode == SDLK_a) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.MoveLeft, IsDown); - } else if(KeyCode == SDLK_d) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.MoveRight, IsDown); - } else if(KeyCode == SDLK_q) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.LeftShoulder, IsDown); - } else if(KeyCode == SDLK_e) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.RightShoulder, IsDown); - } else if(KeyCode == SDLK_UP) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.ActionUp, IsDown); - } else if(KeyCode == SDLK_DOWN) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.ActionDown, IsDown); - } else if(KeyCode == SDLK_LEFT) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.ActionLeft, IsDown); - } else if(KeyCode == SDLK_RIGHT) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.ActionRight, IsDown); - } else if(KeyCode == SDLK_ESCAPE) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.Back, IsDown); - } else if(KeyCode == SDLK_SPACE) { - SDLProcessKeyboardMessage( - &KeyboardController->u.s.Start, IsDown); + if(event.key.repeat == 0) { + if(key_code == SDLK_W) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.move_up, is_down); + } else if(key_code == SDLK_S) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.move_down, is_down); + } else if(key_code == SDLK_A) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.move_left, is_down); + } else if(key_code == SDLK_D) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.move_right, is_down); + } else if(key_code == SDLK_Q) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.left_shoulder, is_down); + } else if(key_code == SDLK_E) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.right_shoulder, is_down); + } else if(key_code == SDLK_UP) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.action_up, is_down); + } else if(key_code == SDLK_DOWN) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.action_down, is_down); + } else if(key_code == SDLK_LEFT) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.action_left, is_down); + } else if(key_code == SDLK_RIGHT) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.action_right, is_down); + } else if(key_code == SDLK_ESCAPE) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.back, is_down); + } else if(key_code == SDLK_SPACE) { + sdl_process_keyboard_message( + &keyboard_controller->u.s.start, is_down); } } - if(WasDown) { + if(was_down) { /* NOTE: If your window manager already uses an Alt+F4 * keybind to close programs, then we are likely * to see SDL_QUIT event occur before our keybind. */ - int AltKeyWasDown = (Event.key.keysym.mod & KMOD_ALT); + int alt_key_was_down = (event.key.mod & SDL_KMOD_ALT); - if(KeyCode == SDLK_F4 && AltKeyWasDown) - GlobalRunning = 0; + if(key_code == SDLK_F4 && alt_key_was_down) + global_running = 0; #if BUILD_INTERNAL - if(KeyCode == SDLK_ESCAPE) - GlobalRunning = 0; + if(key_code == SDLK_ESCAPE) + global_running = 0; #endif - if((KeyCode == SDLK_RETURN) && AltKeyWasDown) { - SDLToggleFullscreen(Window); + if((key_code == SDLK_RETURN) && alt_key_was_down) { + sdl_toggle_fullscreen(window); } } } break; default: { - HandleEvent(&Event); + HandleEvent(&event); } break; } } } -static float SDLProcessInputStickValue(float Value, int DeadZoneThreshold) +static float +sdl_process_input_stick_value(float value, int dead_zone_threshold) { - float Result = 0.0f; - if(Value < -(float)DeadZoneThreshold) - Result = (Value + (float)DeadZoneThreshold) / - (32768.0f - (float)DeadZoneThreshold); - else if(Value > (float)DeadZoneThreshold) - Result = (Value + (float)DeadZoneThreshold) / - (32767.0f - (float)DeadZoneThreshold); - return Result; + float result = 0.0f; + if(value < -(float)dead_zone_threshold) + result = (value + (float)dead_zone_threshold) / + (32768.0f - (float)dead_zone_threshold); + else if(value > (float)dead_zone_threshold) + result = (value + (float)dead_zone_threshold) / + (32767.0f - (float)dead_zone_threshold); + return result; } #define DEFAULT_REFRESH_RATE 60 -static int SDLGetWindowRefreshRate(SDL_Window *Window) +static int sdl_get_window_refresh_rate(SDL_Window *window) { - int DisplayIndex = SDL_GetWindowDisplayIndex(Window); + unsigned int display_index; - SDL_DisplayMode Mode; - if(SDL_GetDesktopDisplayMode(DisplayIndex, &Mode) != 0) + const SDL_DisplayMode *mode; + + display_index = SDL_GetDisplayForWindow(window); + + mode = SDL_GetDesktopDisplayMode(display_index); + if(!mode) return DEFAULT_REFRESH_RATE; - if(Mode.refresh_rate == 0) + if(mode->refresh_rate == 0) return DEFAULT_REFRESH_RATE; - return Mode.refresh_rate; + return mode->refresh_rate; } -static unsigned long long SDLGetWallClock() +static unsigned long long sdl_get_wall_clock() { return SDL_GetPerformanceCounter(); } -static float SDLGetSecondsElapsed(unsigned long long Start, - unsigned long long End) +static float sdl_get_seconds_elapsed(unsigned long long start, + unsigned long long end) { - return (float)(End - Start) / (float)GlobalPerfCountFrequency; + return (float)(end - start) / (float)global_perf_count_frequency; } struct sdl_game_code { - void *GameCodeDLL; - unsigned int DLLLastWriteTime; + void *game_code_dll; + unsigned int dll_last_write_time; - void (*UpdateAndRender)(struct thread_context *Thread, - struct game_memory *, - struct game_input *, - struct game_offscreen_buffer *, - struct game_sound_output_buffer *); + void (*update_and_render)(struct thread_context *Thread, + struct game_memory *, + struct game_input *, + struct game_offscreen_buffer *, + struct game_sound_output_buffer *); - int IsValid; + int is_valid; }; -static unsigned int GetLastWriteTime(const char *FileName) +static unsigned int get_last_write_time(const char *file_name) { struct stat file_info; memset(&file_info, 0, sizeof(file_info)); - if(stat(FileName, &file_info) != 0) { + if(stat(file_name, &file_info) != 0) { /* TODO: Diagnostic. perror("stat failed"); */ } @@ -611,73 +638,71 @@ static unsigned int GetLastWriteTime(const char *FileName) #define GAME_DLL_NAME "libhandmade.so" #elif OS_WINDOWS #define GAME_DLL_NAME "handmade.dll" -#else -#error Unknown OS: please specify GAME_DLL_NAME #endif -static struct sdl_game_code SDLLoadGameCode(char *DLLPath) +static struct sdl_game_code sdl_load_game_code(char *dll_path) { - struct sdl_game_code Result; - memset(&Result, 0, sizeof(Result)); + struct sdl_game_code result; + memset(&result, 0, sizeof(result)); #if OS_MACOS || OS_LINUX - Result.GameCodeDLL = dlopen(DLLPath, RTLD_NOW); + result.game_code_dll = dlopen(dll_path, RTLD_NOW); #elif OS_WINDOWS - Result.GameCodeDLL = LoadLibraryA(DLLPath); + result.game_code_dll = LoadLibraryA(dll_path); #else #error Unknown OS: implement DLL loading... #endif - if(Result.GameCodeDLL) { - Result.DLLLastWriteTime = GetLastWriteTime(DLLPath); + if(result.game_code_dll) { + result.dll_last_write_time = get_last_write_time(dll_path); #if OS_MACOS || OS_LINUX - Result.UpdateAndRender = (void(*)(struct thread_context *, + result.update_and_render = (void(*)(struct thread_context *, struct game_memory *, struct game_input *, struct game_offscreen_buffer *, - struct game_sound_output_buffer *))dlsym(Result.GameCodeDLL, - "UpdateAndRender"); + struct game_sound_output_buffer *))dlsym(result.game_code_dll, + "update_and_render"); #elif OS_WINDOWS - Result.UpdateAndRender = (void(*)(thread_context *, game_memory *, + result.update_and_render = (void(*)(thread_context *, game_memory *, game_input *, game_offscreen_buffer *, - game_sound_output_buffer *))GetProcAddress(Result.GameCodeDLL, - "UpdateAndRender"); + game_sound_output_buffer *))GetProcAddress(result.game_code_dll, + "update_and_render"); #else #error Unknown OS: implement DLL loading... #endif - if(!Result.UpdateAndRender) { + if(!result.update_and_render) { /* TODO: Diagnostic. dlerror() */ } - Result.IsValid = Result.UpdateAndRender ? 1 : 0; + result.is_valid = result.update_and_render ? 1 : 0; } else { /* TODO: Diagnostic. dlerror() */ } - if(!Result.IsValid) { - Result.UpdateAndRender = 0; + if(!result.is_valid) { + result.update_and_render = 0; } - return Result; + return result; } -static void SDLUnloadGameCode(struct sdl_game_code *GameCode) +static void sdl_unload_game_code(struct sdl_game_code *game_code) { - if(GameCode->GameCodeDLL) { + if(game_code->game_code_dll) { #if OS_MACOS || OS_LINUX - dlclose(GameCode->GameCodeDLL); /* NOTE: Might fail. */ + dlclose(game_code->game_code_dll); /* NOTE: Might fail. */ #elif OS_WINDOWS - FreeLibrary(GameCode->GameCodeDLL); + FreeLibrary(game_code->game_code_dll); #else #error Unknown OS: implement closing of DLL #endif } - GameCode->IsValid = 0; - GameCode->UpdateAndRender = 0; + game_code->is_valid = 0; + game_code->update_and_render = 0; } -void GetExecutablePath(char *path, size_t path_size) +void get_executable_path(char *path, size_t path_size) { #if OS_MACOS unsigned int size; @@ -703,25 +728,23 @@ void GetExecutablePath(char *path, size_t path_size) } #elif OS_WINDOWS GetModuleFileName(NULL, path, (DWORD)path_size); // TODO: hm... -#else -#error Unknown OS: Implement getting executable location. #endif } } -static void SDLGetEXEDirPath(char *path, size_t path_size) +static void sdl_get_exe_dir_path(char *path, size_t path_size) { -#if OS_MACOS || OS_LINUX - char delimeter = '/'; -#elif OS_WINDOWS - char delimeter = '\\'; -#else -#error Unknown OS: OS uses forward or backward slashes for paths? -#endif + char delimeter; unsigned int len, i; - GetExecutablePath(path, path_size); +#if OS_MACOS || OS_LINUX + delimeter = '/'; +#elif OS_WINDOWS + delimeter = '\\'; +#endif + + get_executable_path(path, path_size); len = str_len(path); i = len; @@ -731,7 +754,7 @@ static void SDLGetEXEDirPath(char *path, size_t path_size) path[i+1] = '\0'; } -static void SDLGetDLLPath(char *path, size_t path_size, char *exe_path) +static void sdl_get_dll_path(char *path, size_t path_size, char *exe_path) { snprintf(path, path_size, "%s%s", exe_path, GAME_DLL_NAME); } @@ -745,41 +768,42 @@ U64 __rdtsc() int main(int argc, char *argv[]) { - struct sdl_state SDLState; + struct sdl_state sdl_state; - SDL_Window *Window; + SDL_Window *window; - memset(&SDLState, 0, sizeof(SDLState)); + memset(&sdl_state, 0, sizeof(sdl_state)); - SDLGetEXEDirPath(SDLState.EXEDirPath, sizeof(SDLState.EXEDirPath)); - SDLGetDLLPath(SDLState.DLLPath, sizeof(SDLState.DLLPath), - SDLState.EXEDirPath); + sdl_get_exe_dir_path(sdl_state.exe_dir_path, sizeof(sdl_state.exe_dir_path)); + sdl_get_dll_path(sdl_state.dll_path, sizeof(sdl_state.dll_path), + sdl_state.exe_dir_path); - if(SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO | SDL_INIT_GAMECONTROLLER)) { + if(SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO | SDL_INIT_GAMEPAD)) { /* TODO: This didn't work . . . */ } - SDLInitControllers(); + sdl_init_controllers(); /* NOTE: Create hidden window so that a blank window doesn't appear * before everything is ready. */ /* TODO: SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, in non-debug * build */ - Window = SDL_CreateWindow("Handmade Hero", - SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, - RESOLUTION_WIDTH+20, RESOLUTION_HEIGHT+20, - SDL_WINDOW_HIDDEN | SDL_WINDOW_RESIZABLE/* | - SDL_WINDOW_ALWAYS_ON_TOP*/); - if(Window) { - SDL_DisplayMode display_mode; + window = SDL_CreateWindow("Handmade Hero", + RESOLUTION_WIDTH+20, RESOLUTION_HEIGHT+20, + SDL_WINDOW_HIDDEN | SDL_WINDOW_RESIZABLE | + SDL_WINDOW_HIGH_PIXEL_DENSITY /*| + SDL_WINDOW_ALWAYS_ON_TOP*/); + if(window) { + const SDL_DisplayMode *display_mode; - SDL_Renderer *Renderer; + SDL_Renderer *renderer; - LastWindow = Window; + last_window = window; - SDL_GetCurrentDisplayMode(0, &display_mode); + display_mode = SDL_GetCurrentDisplayMode(0); - Renderer = SDL_CreateRenderer(Window, -1, SDL_RENDERER_PRESENTVSYNC); + renderer = SDL_CreateRenderer(window, 0); + SDL_SetRenderVSync(renderer, SDL_RENDERER_VSYNC_ADAPTIVE); /* NOTE: For future reference, the custom window bar should use * SDL_SetWindowHitTest to define areas that will be used to drag @@ -790,423 +814,432 @@ int main(int argc, char *argv[]) /* NOTE: This means that we need to readraw to even resize the * window, otherwise the window frame will appear outdated to * its actual size. */ - /* SDL_RenderPresent(Renderer) is enough to display the window. */ - if(Renderer) { - struct thread_context TempContext; + /* SDL_RenderPresent(renderer) is enough to display the window. */ + if(renderer) { + struct thread_context temp_context; - SDL_Cursor *PointerCursor; + SDL_Cursor *pointer_cursor; - SDL_Rect UsableDisplayRect; + SDL_Rect usable_display_rect; - struct sdl_window_size CurrentWindowSize; + struct sdl_window_size current_window_size; - struct sdl_sound_output SoundOutput; + struct sdl_sound_output sound_output; #if BUILD_DEBUG - void *BaseAddress = (void *)TB(2); + void *base_address = (void *)TB(2); #else - void *BaseAddress = (void *)(0); + void *base_address = (void *)(0); #endif - struct game_memory GameMemory; + struct game_memory game_memory; - memset(&TempContext, 0, sizeof(TempContext)); + memset(&temp_context, 0, sizeof(temp_context)); /* TODO: Make it a global. */ - PointerCursor = SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_ARROW); - SDL_SetCursor(PointerCursor); + pointer_cursor = SDL_CreateSystemCursor(SDL_SYSTEM_CURSOR_DEFAULT); + SDL_SetCursor(pointer_cursor); #if !BUILD_INTERNAL if(SDL_ShowCursor(SDL_DISABLE) < 0) { /* TODO: This didn't work . . . SDL_GetError() */ } #endif - SDL_GetDisplayUsableBounds(0, &UsableDisplayRect); - CurrentWindowSize = SDLGetBorderedWindowSize(Window); - SDLSetBorderedWindowPosition(Window, - (UsableDisplayRect.x + UsableDisplayRect.w - - CurrentWindowSize.Width), - (UsableDisplayRect.y + UsableDisplayRect.h - - CurrentWindowSize.Height)); + SDL_GetDisplayUsableBounds(0, &usable_display_rect); + current_window_size = sdl_get_bordered_window_size(window); + sdl_set_bordered_window_position(window, + (usable_display_rect.x + usable_display_rect.w - + current_window_size.width), + (usable_display_rect.y + usable_display_rect.h - + current_window_size.height)); - GlobalRunning = 1; + global_running = 1; /* sdl_window_dimension Dimension = - SDLGetWindowDimension(Window); */ - /* SDLResizeTexture(&GlobalBackbuffer, Renderer, - Dimension.Width, Dimension.Height); */ - SDLResizeTexture(&GlobalBackbuffer, Renderer, - RESOLUTION_WIDTH, RESOLUTION_HEIGHT); + SDLGetWindowDimension(window); */ + /* sdl_resize_texture(&global_backbuffer, renderer, + Dimension.Width, Dimension.Height); */ + sdl_resize_texture(&global_backbuffer, renderer, + RESOLUTION_WIDTH, RESOLUTION_HEIGHT); - memset(&SoundOutput, 0, sizeof(SoundOutput)); - SoundOutput.SamplesPerSecond = 48000; - SoundOutput.BytesPerSample = sizeof(short) * 2; - SoundOutput.SecondaryBufferSize = - SoundOutput.SamplesPerSecond * SoundOutput.BytesPerSample; - SoundOutput.LatencySampleCount = - SoundOutput.SamplesPerSecond / 15; + memset(&sound_output, 0, sizeof(sound_output)); + sound_output.samples_per_second = 48000; + sound_output.bytes_per_sample = sizeof(short) * 2; + sound_output.secondary_buffer_size = + sound_output.samples_per_second * + sound_output.bytes_per_sample; + sound_output.latency_sample_count = + sound_output.samples_per_second / 15; - SDLInitSound(SoundOutput.SamplesPerSecond, - SoundOutput.SamplesPerSecond * SoundOutput.BytesPerSample / +#if 0 + sdl_init_sound(sound_output.SamplesPerSecond, + sound_output.SamplesPerSecond * sound_output.BytesPerSample / 60); /* TODO: Should be paused until we have sound to play. */ SDL_PauseAudio(0); - SoundOutput.Samples = calloc(SoundOutput.SamplesPerSecond, - SoundOutput.BytesPerSample); - /*SoundOutput.Samples = malloc(SoundOutput.SecondaryBufferSize);*/ + sound_output.Samples = calloc(sound_output.SamplesPerSecond, + sound_output.BytesPerSample); + /*sound_output.Samples = malloc(sound_output.SecondaryBufferSize);*/ /* NOTE: calloc auto clears to zero */ - /* SDLClearSoundBuffer(&SoundOutput); */ + /* sdl_clear_sound_buffer(&sound_output); */ +#endif - memset(&GameMemory, 0, sizeof(GameMemory)); - GameMemory.PermanentStorageSize = MB(64); - GameMemory.TransientStorageSize = GB(1); - GameMemory.DEBUGPlatformReadEntireFile = - &DEBUGPlatformReadEntireFile; - GameMemory.SetProgramIcon = &SetProgramIcon; - /* GameMemory.DEBUGPlatformWriteEntireFile = - &DEBUGPlatformWriteEntireFile; */ - GameMemory.DEBUGPlatformFreeFileMemory = - &DEBUGPlatformFreeFileMemory; + memset(&game_memory, 0, sizeof(game_memory)); + game_memory.permanent_storage_size = MB(64); + game_memory.transient_storage_size = GB(1); + game_memory.debug_platform_read_entire_file = + &debug_platform_read_entire_file; + game_memory.SetProgramIcon = &SetProgramIcon; + /* game_memory.DEBUGPlatformWriteEntireFile = + &debug_platform_write_entire_file; */ + game_memory.debug_platform_free_file_memory = + &debug_platform_free_file_memory; - SDLState.TotalSize = GameMemory.PermanentStorageSize + - GameMemory.TransientStorageSize; + sdl_state.total_size = game_memory.permanent_storage_size + + game_memory.transient_storage_size; #if OS_MACOS || OS_LINUX /* NOTE: On MacOS and Linux, mmap seems to zero-fill anonymous * memory as a side-effect of security. */ - SDLState.GameMmemoryBlock = mmap(BaseAddress, - (size_t)SDLState.TotalSize, + sdl_state.game_memory_block = mmap(base_address, + (size_t)sdl_state.total_size, PROT_READ | PROT_WRITE, MAP_ANON | MAP_PRIVATE, -1, 0); #elif OS_WINDOWS - SDLState.GameMmemoryBlock = VirtualAlloc(BaseAddress, - SDLState.TotalSize, + sdl_state.GameMmemoryBlock = VirtualAlloc(base_address, + sdl_state.TotalSize, MEM_RESERVE | MEM_COMMIT, PAGE_READWRITE); #else #error Unknown OS: please, allocate memory for arena #endif - GameMemory.PermanentStorage = SDLState.GameMmemoryBlock; - GameMemory.TransientStorage = - (unsigned char *)(GameMemory.PermanentStorage) + - GameMemory.PermanentStorageSize; + game_memory.permanent_storage = sdl_state.game_memory_block; + game_memory.transient_storage = + (unsigned char *)(game_memory.permanent_storage) + + game_memory.permanent_storage_size; - if(SoundOutput.Samples && - GameMemory.PermanentStorage && - GameMemory.TransientStorage) + if(/*sound_output.Samples &&*/ + game_memory.permanent_storage && + game_memory.transient_storage) { - struct game_input Input[2]; + struct game_input input[2]; - unsigned long long LastCounter; - unsigned long long LastCycleCount; + unsigned long long last_counter; + unsigned long long last_cycle_count; - int MonitorRefreshHz, GameUpdateHz; - float TargetSecondsPerFrame; + int monitor_refresh_hz, game_update_hz; + float target_seconds_per_frame; - struct game_input *NewInput, *OldInput; + struct game_input *new_input, *old_input; - struct sdl_game_code Game; + struct sdl_game_code game; - unsigned long long FPSLastCounter; + unsigned long long fps_last_counter; - MonitorRefreshHz = SDLGetWindowRefreshRate(Window); - /*GameUpdateHz = MonitorRefreshHz;*/ - GameUpdateHz = 30; /* NOTE: Temporarily target 30 FPS. */ - TargetSecondsPerFrame = 1.0f / (float)GameUpdateHz; + monitor_refresh_hz = sdl_get_window_refresh_rate(window); + /*game_update_hz = monitor_refresh_hz;*/ + game_update_hz = 30; /* NOTE: Temporarily target 30 FPS. */ + target_seconds_per_frame = 1.0f / (float)game_update_hz; - NewInput = &Input[0]; - OldInput = &Input[1]; - memset(Input, 0, sizeof(Input)); + new_input = &input[0]; + old_input = &input[1]; + memset(input, 0, sizeof(input)); - GlobalPerfCountFrequency = SDL_GetPerformanceFrequency(); + global_perf_count_frequency = SDL_GetPerformanceFrequency(); - Game = SDLLoadGameCode(SDLState.DLLPath); + game = sdl_load_game_code(sdl_state.dll_path); - SDL_ShowWindow(Window); // Everything is ready; display the window. + SDL_ShowWindow(window); // Everything is ready; display the window. - FPSLastCounter = SDLGetWallClock(); + fps_last_counter = sdl_get_wall_clock(); - while(GlobalRunning) { - unsigned int NewDLLWriteTime; + while(global_running) { + unsigned int new_dll_write_time; - int MouseX, MouseY; + float mouse_x, mouse_y; - int WindowX, WindowY; + int window_x, window_y; - unsigned int SDLMouseButtons; + unsigned int sdl_mouse_buttons; - struct game_controller_input *OldKeyboardController, - *NewKeyboardController; - struct game_controller_input ZeroController; + struct game_controller_input *old_keyboard_controller, + *new_keyboard_controller; + struct game_controller_input zero_controller; - unsigned int ButtonIndex; - unsigned int ControllerIndex; + unsigned int button_index; + unsigned int controller_index; - int TargetQueueBytes; - int BytesToWrite; - struct game_sound_output_buffer SoundBuffer; + int target_queue_bytes; + int bytes_to_write; + struct game_sound_output_buffer sound_buffer; - struct thread_context Context; + struct thread_context context; - struct game_offscreen_buffer Buffer; + struct game_offscreen_buffer buffer; - unsigned long long WorkCounter; - float WorkSecondsElapsed; - float SecondsElapsedForFrame; + unsigned long long work_counter; + float work_seconds_elapsed; + float seconds_elapsed_for_frame; - unsigned long long EndCounter; + unsigned long long end_counter; - float MSPerFrame; - float FPS; + float ms_per_frame; + float fps; - NewInput->dtForFrame = TargetSecondsPerFrame; + new_input->dt_for_frame = target_seconds_per_frame; - LastCounter = SDLGetWallClock(); + last_counter = sdl_get_wall_clock(); /* NOTE: rdtsc reports clock cylces, however it is not * meant for really precise profiler work as the value * returned is varied. Also, __rdtsc is not available * on MacOS ARM; I have not checked MacOS x64. */ - LastCycleCount = __rdtsc(); + last_cycle_count = __rdtsc(); - NewDLLWriteTime = GetLastWriteTime(SDLState.DLLPath); - if(NewDLLWriteTime > Game.DLLLastWriteTime) { - SDLUnloadGameCode(&Game); - Game = SDLLoadGameCode(SDLState.DLLPath); + new_dll_write_time = get_last_write_time(sdl_state.dll_path); + if(new_dll_write_time > game.dll_last_write_time) { + sdl_unload_game_code(&game); + game = sdl_load_game_code(sdl_state.dll_path); } - SDL_GetGlobalMouseState(&MouseX, &MouseY); + SDL_GetGlobalMouseState(&mouse_x, &mouse_y); - SDL_GetWindowPosition(Window, &WindowX, &WindowY); + SDL_GetWindowPosition(window, &window_x, &window_y); - NewInput->MouseX = MouseX - WindowX; - NewInput->MouseY = MouseY - WindowY; + new_input->mouse_x = (int)mouse_x - window_x; + new_input->mouse_y = (int)mouse_y - window_y; - SDLMouseButtons = SDL_GetMouseState(NULL, NULL); - NewInput->MouseZ = 0; /* TODO: Support mouse wheel? */ - SDLProcessKeyboardMessage(&(NewInput->MouseButtons[0]), - SDL_BUTTON_LMASK & SDLMouseButtons); - SDLProcessKeyboardMessage(&(NewInput->MouseButtons[1]), - SDL_BUTTON_MMASK & SDLMouseButtons); - SDLProcessKeyboardMessage(&(NewInput->MouseButtons[2]), - SDL_BUTTON_RMASK & SDLMouseButtons); + sdl_mouse_buttons = SDL_GetMouseState(NULL, NULL); + new_input->mouse_z = 0; /* TODO: Support mouse wheel? */ + sdl_process_keyboard_message(&(new_input->mouse_buttons[0]), + SDL_BUTTON_LMASK & sdl_mouse_buttons); + sdl_process_keyboard_message(&(new_input->mouse_buttons[1]), + SDL_BUTTON_MMASK & sdl_mouse_buttons); + sdl_process_keyboard_message(&(new_input->mouse_buttons[2]), + SDL_BUTTON_RMASK & sdl_mouse_buttons); /* WARNING: TODO: SDL_BUTTON_X1MASK and SDL_BUTTON_X2MASK * cannot be on at the same time for some reason. */ - SDLProcessKeyboardMessage(&(NewInput->MouseButtons[3]), - SDL_BUTTON_X1MASK & SDLMouseButtons); - SDLProcessKeyboardMessage(&(NewInput->MouseButtons[4]), - SDL_BUTTON_X2MASK & SDLMouseButtons); + sdl_process_keyboard_message(&(new_input->mouse_buttons[3]), + SDL_BUTTON_X1MASK & sdl_mouse_buttons); + sdl_process_keyboard_message(&(new_input->mouse_buttons[4]), + SDL_BUTTON_X2MASK & sdl_mouse_buttons); - OldKeyboardController = GetController(OldInput, 0); - NewKeyboardController = GetController(NewInput, 0); - memset(&ZeroController, 0, sizeof(ZeroController)); - *NewKeyboardController = ZeroController; - NewKeyboardController->IsConnected = 1; + old_keyboard_controller = GetController(old_input, 0); + new_keyboard_controller = GetController(new_input, 0); + memset(&zero_controller, 0, sizeof(zero_controller)); + *new_keyboard_controller = zero_controller; + new_keyboard_controller->is_connected = 1; - for(ButtonIndex = 0; - ButtonIndex < - ARRAY_SIZE(NewKeyboardController->u.Buttons); - ButtonIndex++) + for(button_index = 0; + button_index < + ARRAY_SIZE(new_keyboard_controller->u.buttons); + button_index++) { - NewKeyboardController->u. - Buttons[ButtonIndex].EndedDown = - OldKeyboardController->u. - Buttons[ButtonIndex].EndedDown; + new_keyboard_controller->u. + buttons[button_index].ended_down = + old_keyboard_controller->u. + buttons[button_index].ended_down; } - SDLProcessMessages(&SDLState, NewKeyboardController); + sdl_process_messages(&sdl_state, new_keyboard_controller); - for(ControllerIndex = 0; - ControllerIndex < MAX_CONTROLLERS; - ControllerIndex++) + for(controller_index = 0; + controller_index < MAX_CONTROLLERS; + controller_index++) { - struct game_controller_input *OldController, - *NewController; + struct game_controller_input *old_controller, + *new_controller; - OldController = - GetController(OldInput, ControllerIndex+1); - NewController = - GetController(NewInput, ControllerIndex+1); + old_controller = + GetController(old_input, controller_index+1); + new_controller = + GetController(new_input, controller_index+1); - if(ControllerHandles[ControllerIndex] != 0 && - SDL_GameControllerGetAttached( - ControllerHandles[ControllerIndex])) +#if 1 + if(controller_handles[controller_index] != 0 && + SDL_GamepadConnected( + controller_handles[controller_index])) { - short StickX, StickY; + short stick_x, stick_y; - float Threshold; + float threshold; - NewController->IsAnalog = - OldController->IsAnalog; - NewController->IsConnected = 1; + new_controller->is_analog = + old_controller->is_analog; + new_controller->is_connected = 1; - StickX = SDL_GameControllerGetAxis( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_AXIS_LEFTX); - StickY = SDL_GameControllerGetAxis( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_AXIS_LEFTY); + stick_x = SDL_GetGamepadAxis( + controller_handles[controller_index], + SDL_GAMEPAD_AXIS_LEFTX); + stick_y = SDL_GetGamepadAxis( + controller_handles[controller_index], + SDL_GAMEPAD_AXIS_LEFTY); - NewController->IsAnalog = 1; - NewController->StickAverageX = - SDLProcessInputStickValue((float)StickX, + new_controller->is_analog = 1; + new_controller->stick_average_x = + sdl_process_input_stick_value((float)stick_x, CONTROLLER_LEFT_THUMB_DEADZONE); - NewController->StickAverageY = - SDLProcessInputStickValue((float)StickY, + new_controller->stick_average_y = + sdl_process_input_stick_value((float)stick_y, CONTROLLER_LEFT_THUMB_DEADZONE); - if(NewController->StickAverageX != 0.0f || - NewController->StickAverageY != 0.0f) + if(new_controller->stick_average_x != 0.0f || + new_controller->stick_average_y != 0.0f) { - NewController->IsAnalog = 1; + new_controller->is_analog = 1; } - if(SDL_GameControllerGetButton( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_BUTTON_DPAD_UP)) + if(SDL_GetGamepadButton( + controller_handles[controller_index], + SDL_GAMEPAD_BUTTON_DPAD_UP)) { - NewController->StickAverageY = -1.0f; - NewController->IsAnalog = 0; + new_controller->stick_average_y = -1.0f; + new_controller->is_analog = 0; } - if(SDL_GameControllerGetButton( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_BUTTON_DPAD_DOWN)) + if(SDL_GetGamepadButton( + controller_handles[controller_index], + SDL_GAMEPAD_BUTTON_DPAD_DOWN)) { - NewController->StickAverageY = 1.0f; - NewController->IsAnalog = 0; + new_controller->stick_average_y = 1.0f; + new_controller->is_analog = 0; } - if(SDL_GameControllerGetButton( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_BUTTON_DPAD_LEFT)) + if(SDL_GetGamepadButton( + controller_handles[controller_index], + SDL_GAMEPAD_BUTTON_DPAD_LEFT)) { - NewController->StickAverageX = -1.0f; - NewController->IsAnalog = 0; + new_controller->stick_average_x = -1.0f; + new_controller->is_analog = 0; } - if(SDL_GameControllerGetButton( - ControllerHandles[ControllerIndex], - SDL_CONTROLLER_BUTTON_DPAD_RIGHT)) + if(SDL_GetGamepadButton( + controller_handles[controller_index], + SDL_GAMEPAD_BUTTON_DPAD_RIGHT)) { - NewController->StickAverageX = 1.0f; - NewController->IsAnalog = 0; + new_controller->stick_average_x = 1.0f; + new_controller->is_analog = 0; } - Threshold = 0.5f; - SDLProcessInputDigitalButton( - ControllerHandles[(NewController-> - StickAverageY < -Threshold) ? 1 : 0], - &OldController->u.s.MoveUp, - SDL_CONTROLLER_BUTTON_A, - &NewController->u.s.MoveUp); - SDLProcessInputDigitalButton( - ControllerHandles[(NewController-> - StickAverageY > Threshold) ? 1 : 0], - &OldController->u.s.MoveDown, - SDL_CONTROLLER_BUTTON_A, - &NewController->u.s.MoveDown); - SDLProcessInputDigitalButton( - ControllerHandles[(NewController-> - StickAverageX < -Threshold) ? 1 : 0], - &OldController->u.s.MoveLeft, - SDL_CONTROLLER_BUTTON_A, - &NewController->u.s.MoveLeft); - SDLProcessInputDigitalButton( - ControllerHandles[(NewController-> - StickAverageX > Threshold) ? 1 : 0], - &OldController->u.s.MoveRight, - SDL_CONTROLLER_BUTTON_A, - &NewController->u.s.MoveRight); + threshold = 0.5f; + sdl_process_input_digital_button( + controller_handles[(new_controller-> + stick_average_y < -threshold) ? 1 : 0], + &old_controller->u.s.move_up, + SDL_GAMEPAD_BUTTON_SOUTH, + &new_controller->u.s.move_up); + sdl_process_input_digital_button( + controller_handles[(new_controller-> + stick_average_y > threshold) ? 1 : 0], + &old_controller->u.s.move_down, + SDL_GAMEPAD_BUTTON_SOUTH, + &new_controller->u.s.move_down); + sdl_process_input_digital_button( + controller_handles[(new_controller-> + stick_average_x < -threshold) ? 1 : 0], + &old_controller->u.s.move_left, + SDL_GAMEPAD_BUTTON_SOUTH, + &new_controller->u.s.move_left); + sdl_process_input_digital_button( + controller_handles[(new_controller-> + stick_average_x > threshold) ? 1 : 0], + &old_controller->u.s.move_right, + SDL_GAMEPAD_BUTTON_SOUTH, + &new_controller->u.s.move_right); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.ActionDown, - SDL_CONTROLLER_BUTTON_A, - &NewController->u.s.ActionDown); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.ActionRight, - SDL_CONTROLLER_BUTTON_B, - &NewController->u.s.ActionRight); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.ActionLeft, - SDL_CONTROLLER_BUTTON_X, - &NewController->u.s.ActionLeft); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.ActionUp, - SDL_CONTROLLER_BUTTON_Y, - &NewController->u.s.ActionUp); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.LeftShoulder, - SDL_CONTROLLER_BUTTON_LEFTSHOULDER, - &NewController->u.s.LeftShoulder); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.RightShoulder, - SDL_CONTROLLER_BUTTON_RIGHTSHOULDER, - &NewController->u.s.RightShoulder); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.action_down, + SDL_GAMEPAD_BUTTON_SOUTH, + &new_controller->u.s.action_down); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.action_right, + SDL_GAMEPAD_BUTTON_EAST, + &new_controller->u.s.action_right); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.action_left, + SDL_GAMEPAD_BUTTON_WEST, + &new_controller->u.s.action_left); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.action_up, + SDL_GAMEPAD_BUTTON_NORTH, + &new_controller->u.s.action_up); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.left_shoulder, + SDL_GAMEPAD_BUTTON_LEFT_SHOULDER, + &new_controller->u.s.left_shoulder); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.right_shoulder, + SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER, + &new_controller->u.s.right_shoulder); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.Start, - SDL_CONTROLLER_BUTTON_START, - &NewController->u.s.Start); - SDLProcessInputDigitalButton( - ControllerHandles[ControllerIndex], - &OldController->u.s.Back, - SDL_CONTROLLER_BUTTON_BACK, - &NewController->u.s.Back); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.start, + SDL_GAMEPAD_BUTTON_START, + &new_controller->u.s.start); + sdl_process_input_digital_button( + controller_handles[controller_index], + &old_controller->u.s.back, + SDL_GAMEPAD_BUTTON_BACK, + &new_controller->u.s.back); } else { /* NOTE: This controller is not plugged in. */ - NewController->IsConnected = 0; + new_controller->is_connected = 0; } +#endif } - TargetQueueBytes = SoundOutput.LatencySampleCount * - SoundOutput.BytesPerSample; - BytesToWrite = - TargetQueueBytes - SDL_GetQueuedAudioSize(1); - SoundBuffer.SamplesPerSecond = - SoundOutput.SamplesPerSecond; - SoundBuffer.SampleCount = - BytesToWrite / SoundOutput.BytesPerSample; - SoundBuffer.Samples = (short *)SoundOutput.Samples; +#if 0 + target_queue_bytes = sound_output.LatencySampleCount * + sound_output.BytesPerSample; + bytes_to_write = + target_queue_bytes - SDL_GetQueuedAudioSize(1); + sound_buffer.SamplesPerSecond = + sound_output.SamplesPerSecond; + sound_buffer.SampleCount = + bytes_to_write / sound_output.BytesPerSample; + sound_buffer.Samples = (short *)sound_output.Samples; +#endif - memset(&Context, 0, sizeof(Context)); + memset(&context, 0, sizeof(context)); - Buffer.Memory = GlobalBackbuffer.Memory; - Buffer.Width = GlobalBackbuffer.Width; - Buffer.Height = GlobalBackbuffer.Height; - Buffer.BytesPerPixel = 4; - Buffer.Pitch = GlobalBackbuffer.Pitch; + buffer.memory = global_backbuffer.memory; + buffer.width = global_backbuffer.width; + buffer.height = global_backbuffer.height; + buffer.bytes_per_pixel = 4; + buffer.pitch = global_backbuffer.pitch; - if(Game.UpdateAndRender) { - Game.UpdateAndRender(&Context, &GameMemory, - NewInput, &Buffer, - &SoundBuffer); + if(game.update_and_render) { + game.update_and_render(&context, &game_memory, + new_input, &buffer, + &sound_buffer); } - SDLFillSoundBuffer(&SoundOutput, BytesToWrite); + /* + sdl_fill_sound_buffer(&sound_output, bytes_to_write); + */ - WorkCounter = SDLGetWallClock(); - WorkSecondsElapsed = - SDLGetSecondsElapsed(LastCounter, WorkCounter); + work_counter = sdl_get_wall_clock(); + work_seconds_elapsed = + sdl_get_seconds_elapsed(last_counter, work_counter); - SecondsElapsedForFrame = WorkSecondsElapsed; - if(SecondsElapsedForFrame < TargetSecondsPerFrame) { - while(SecondsElapsedForFrame < TargetSecondsPerFrame) + seconds_elapsed_for_frame = work_seconds_elapsed; + if(seconds_elapsed_for_frame < target_seconds_per_frame) { + while(seconds_elapsed_for_frame < target_seconds_per_frame) { - SecondsElapsedForFrame = - SDLGetSecondsElapsed(LastCounter, - SDLGetWallClock()); - if(TargetSecondsPerFrame - - SecondsElapsedForFrame >= 0.0f) + seconds_elapsed_for_frame = + sdl_get_seconds_elapsed(last_counter, + sdl_get_wall_clock()); + if(target_seconds_per_frame - + seconds_elapsed_for_frame >= 0.0f) { SDL_Delay((unsigned int)( - (TargetSecondsPerFrame - - SecondsElapsedForFrame) * 1000.0)); + (target_seconds_per_frame - + seconds_elapsed_for_frame) * 1000.0)); } } } else { @@ -1214,46 +1247,46 @@ int main(int argc, char *argv[]) /* TODO: Logging. */ } - EndCounter = SDLGetWallClock(); + end_counter = sdl_get_wall_clock(); - SDLDisplayBufferInWindow(&GlobalBackbuffer, Window, - Renderer); + sdl_display_buffer_in_window(&global_backbuffer, window, + renderer); - MSPerFrame = + ms_per_frame = 1000.0f * - SDLGetSecondsElapsed(LastCounter, EndCounter); - FPS = 1000.0f / MSPerFrame; + sdl_get_seconds_elapsed(last_counter, end_counter); + fps = 1000.0f / ms_per_frame; - LastCounter = EndCounter; + last_counter = end_counter; #if 1 - if(SDLGetSecondsElapsed(FPSLastCounter, - SDLGetWallClock()) > 0.1f) + if(sdl_get_seconds_elapsed(fps_last_counter, + sdl_get_wall_clock()) > 0.1f) { unsigned long long EndCycleCount = __rdtsc(); unsigned long long CyclesElapsed = - EndCycleCount - LastCycleCount; + EndCycleCount - last_cycle_count; double MCPF = ((double)CyclesElapsed / (1000.0 * 1000.0)); /*fprintf(stderr, "%.02f ms/f, %.02f f/s, %.02f mc/f\n", - MSPerFrame, FPS, MCPF);*/ + ms_per_frame, fps;, MCPF);*/ static char fps_buffer[128]; snprintf(fps_buffer, sizeof(fps_buffer), "%.02f ms/f, %.02f f/s, %.02f mc/f", - MSPerFrame, FPS, MCPF); - SDL_SetWindowTitle(Window, + ms_per_frame, fps, MCPF); + SDL_SetWindowTitle(window, (const char *)fps_buffer); - LastCycleCount = EndCycleCount; + last_cycle_count = EndCycleCount; - FPSLastCounter = SDLGetWallClock(); + fps_last_counter = sdl_get_wall_clock(); } #endif - SWAP(struct game_input *, OldInput, NewInput); + SWAP(struct game_input *, old_input, new_input); } } else { /* TODO: Failed to allocate Samples and Sound memory . . . */ @@ -1270,8 +1303,8 @@ int main(int argc, char *argv[]) * clean up state that close communicates to the controller? */ /* SDLDeinitControllers(); */ /* SDL_CloseAudio(); */ - /* SDL_DestroyRenderer(Renderer); */ - /* SDL_DestroyWindow(Window); */ + /* SDL_DestroyRenderer(renderer); */ + /* SDL_DestroyWindow(window); */ /* SDL_Quit(); */ return 0; diff --git a/sdl_handmade.h b/sdl_handmade.h index 4728ede..580f351 100644 --- a/sdl_handmade.h +++ b/sdl_handmade.h @@ -1,43 +1,42 @@ #ifndef SDL_HANDMADE_H #define SDL_HANDMADE_H -#include +#include -#include "core.h" #include "handmade.h" struct sdl_border_size { - int Top; - int Bottom; - int Left; - int Right; + int top; + int bottom; + int left; + int right; }; struct sdl_window_size { - int Width; - int Height; + int width; + int height; }; struct sdl_window_position { - int X; - int Y; + int x; + int y; }; struct offscreen_buffer { /* Pixels are always 32-bit and have the bytes in BGRX (little-endian). */ - SDL_Texture *Texture; - void *Memory; - int Width; - int Height; - int Pitch; + SDL_Texture *texture; + void *memory; + int width; + int height; + int pitch; }; struct sdl_sound_output { - int SamplesPerSecond; - int BytesPerSample; - int SecondaryBufferSize; - int LatencySampleCount; - void *Samples; + int samples_per_second; + int bytes_per_sample; + int secondary_buffer_size; + int latency_sample_count; + void *samples; }; /* TODO: We choose 1024 only because MacOS's MAXPATHLEN says such a value. @@ -45,11 +44,11 @@ struct sdl_sound_output { #define SDL_STATE_PATH_SIZE 1024 struct sdl_state { - unsigned long long TotalSize; - void *GameMmemoryBlock; + unsigned long long total_size; + void *game_memory_block; - char EXEDirPath[SDL_STATE_PATH_SIZE]; - char DLLPath[SDL_STATE_PATH_SIZE]; + char exe_dir_path[SDL_STATE_PATH_SIZE]; + char dll_path[SDL_STATE_PATH_SIZE]; }; #endif