commit cca2d94747c20d40d32eb771c5d8386a355b6431 Author: Rune Date: Thu Mar 5 20:10:53 2026 +0100 add code diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c92fda7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +build +recovery +BeefSpace_User.toml +CxxBuilderPath.toml \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..b21aa1f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "SDL"] + path = SDL + url = https://github.com/libsdl-org/SDL.git diff --git a/BeefProj.toml b/BeefProj.toml new file mode 100644 index 0000000..a994e90 --- /dev/null +++ b/BeefProj.toml @@ -0,0 +1,111 @@ +FileVersion = 1 +Dependencies = {corlib = "*", corlib = "*"} + +[Project] +Name = "SDL3" +TargetType = "BeefLib" +StartupObject = "SDL3.Program" + +[Configs.Debug.Win32] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Debug.Win64] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Debug.Linux32] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Debug.Linux64] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Debug.macOS] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Debug.wasm] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "c:\\Projects\\RandomStuff\\Cpp2Beef_dist\\CxxBuilder\\dist\\CxxBuilder.exe *.c */*.c */windows/*.c render/**.c -- \"cflags=-DSDL_PLATFORM_WINDOWS -I$(ProjectDir)/SDL/include -I$(ProjectDir)/SDL/include/build_config -I$(ProjectDir)/SDL/src\" output=SDL3 \"src=$(ProjectDir)/SDL/src\" \"builddir=$(BuildDir)\" target=$(TargetTriple)\""] + +[Configs.Release.Win32] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Release.Win64] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Release.Linux32] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Release.Linux64] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Release.macOS] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Release.wasm] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "c:\\Projects\\RandomStuff\\Cpp2Beef_dist\\CxxBuilder\\dist\\CxxBuilder.exe *.c */*.c */windows/*.c render/**.c -- \"cflags=-DSDL_PLATFORM_WINDOWS -I$(ProjectDir)/SDL/include -I$(ProjectDir)/SDL/include/build_config -I$(ProjectDir)/SDL/src\" output=SDL3 \"src=$(ProjectDir)/SDL/src\" \"builddir=$(BuildDir)\" target=$(TargetTriple)\""] + +[Configs.Paranoid.Win32] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Paranoid.Win64] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Paranoid.Linux32] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Paranoid.Linux64] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Paranoid.macOS] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Paranoid.wasm] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "c:\\Projects\\RandomStuff\\Cpp2Beef_dist\\CxxBuilder\\dist\\CxxBuilder.exe *.c */*.c */windows/*.c render/**.c -- \"cflags=-DSDL_PLATFORM_WINDOWS -I$(ProjectDir)/SDL/include -I$(ProjectDir)/SDL/include/build_config -I$(ProjectDir)/SDL/src\" output=SDL3 \"src=$(ProjectDir)/SDL/src\" \"builddir=$(BuildDir)\" target=$(TargetTriple)\""] + +[Configs.Test.Win32] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Test.Win64] +LibPaths = ["$(BuildDir)/SDL3.lib"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] +PostBuildCmds = ["CopyToDependents(\"$(BuildDir)/SDL3.dll\")"] + +[Configs.Test.Linux32] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Test.Linux64] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Test.macOS] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "Execute(\"$(Var CxxBuilderPath) --cmake -- output=SDL3 \\\"src=$(ProjectDir)/SDL\\\" \\\"builddir=$(BuildDir)\\\" target=$(TargetTriple) config=$(Configuration)\")"] + +[Configs.Test.wasm] +LibPaths = ["$(BuildDir)/SDL3.a"] +PreBuildCmds = ["ReadFile(\"$(ProjectDir)/CxxBuilderPath.txt\", \"CxxBuilderPath\")", "c:\\Projects\\RandomStuff\\Cpp2Beef_dist\\CxxBuilder\\dist\\CxxBuilder.exe *.c */*.c */windows/*.c render/**.c -- \"cflags=-DSDL_PLATFORM_WINDOWS -I$(ProjectDir)/SDL/include -I$(ProjectDir)/SDL/include/build_config -I$(ProjectDir)/SDL/src\" output=SDL3 \"src=$(ProjectDir)/SDL/src\" \"builddir=$(BuildDir)\" target=$(TargetTriple)\""] diff --git a/BeefSpace.toml b/BeefSpace.toml new file mode 100644 index 0000000..511aace --- /dev/null +++ b/BeefSpace.toml @@ -0,0 +1,6 @@ +FileVersion = 1 +Projects = {SDL3 = {Path = "."}} +ExtraPlatforms = ["Linux32", "Linux64", "macOS", "wasm"] + +[Workspace] +StartupProject = "SDL3" diff --git a/CxxBuilderPath.txt b/CxxBuilderPath.txt new file mode 100644 index 0000000..7e82d2e --- /dev/null +++ b/CxxBuilderPath.txt @@ -0,0 +1 @@ +C:\Users\EW\AppData\Local\BeefLang\BeefManaged\fa90624c843b959aed47a6441dc4c79b92059d61\CxxBuilder\dist\CxxBuilder.exe \ No newline at end of file diff --git a/Example/.gitignore b/Example/.gitignore new file mode 100644 index 0000000..1a97e19 --- /dev/null +++ b/Example/.gitignore @@ -0,0 +1,3 @@ +build +recovery +BeefSpace_User.toml \ No newline at end of file diff --git a/Example/BeefProj.toml b/Example/BeefProj.toml new file mode 100644 index 0000000..bc40f66 --- /dev/null +++ b/Example/BeefProj.toml @@ -0,0 +1,7 @@ +FileVersion = 1 +Dependencies = {corlib = "*", SDL3 = "*"} + +[Project] +Name = "SDL3.Example" +TargetType = "BeefGUIApplication" +StartupObject = "SDL3.Example.Program" diff --git a/Example/BeefSpace.toml b/Example/BeefSpace.toml new file mode 100644 index 0000000..00ffbc9 --- /dev/null +++ b/Example/BeefSpace.toml @@ -0,0 +1,6 @@ +FileVersion = 1 +Projects = {"SDL3.Example" = {Path = "."}, SDL3 = {Path = ".."}} +ExtraPlatforms = ["Linux32", "Linux64", "macOS"] + +[Workspace] +StartupProject = "SDL3.Example" diff --git a/Example/src/Program.bf b/Example/src/Program.bf new file mode 100644 index 0000000..c0a5f0e --- /dev/null +++ b/Example/src/Program.bf @@ -0,0 +1,81 @@ +using System; + +using SDL3; + +namespace SDL3.Example; + +class Program +{ + /* + * This example code creates an SDL window and renderer, and then clears the + * window to a different color every frame, so you'll effectively get a window + * that's smoothly fading between colors. + * + * This code is public domain. Feel free to use it for any purpose! + */ + + /* We will use this renderer to draw into this window every frame. */ + static SDL.Window *window = null; + static SDL.Renderer *renderer = null; + + /* This function runs once at startup. */ + static SDL.AppResult AppInit(void **appstate, int32 argc, char8 **argv) + { + SDL.SetAppMetadata("Example Renderer Clear", "1.0", "com.example.renderer-clear"); + + if (!SDL.Init(.Video)) { + SDL.Log("Couldn't initialize SDL: %s", SDL.GetError()); + return .Failure; + } + + if (!SDL.CreateWindowAndRenderer("examples/renderer/clear", 640, 480, .Resizable, &window, &renderer)) { + SDL.Log("Couldn't create window/renderer: %s", SDL.GetError()); + return .Failure; + } + SDL.SetRenderLogicalPresentation(renderer, 640, 480, .Letterbox); + + return .Continue; /* carry on with the program! */ + } + + /* This function runs when a new event (mouse input, keypresses, etc) occurs. */ + static SDL.AppResult AppEvent(void *appstate, SDL.Event *event) + { + if (event.type == (.)SDL.EventType.Quit) { + return .Success; /* end the program, reporting success to the OS. */ + } + return .Continue; /* carry on with the program! */ + } + + /* This function runs once per frame, and is the heart of the program. */ + static SDL.AppResult AppIterate(void *appstate) + { + double now = ((double)SDL.GetTicks()) / 1000.0; /* convert from milliseconds to seconds. */ + /* choose the color for the frame we will draw. The sine wave trick makes it fade between colors smoothly. */ + float red = (float) (0.5 + 0.5 * SDL.sin(now)); + float green = (float) (0.5 + 0.5 * SDL.sin(now + SDL.PI_D * 2 / 3)); + float blue = (float) (0.5 + 0.5 * SDL.sin(now + SDL.PI_D * 4 / 3)); + SDL.SetRenderDrawColorFloat(renderer, red, green, blue, SDL.ALPHA_OPAQUE_FLOAT); /* new color, full alpha. */ + + /* clear the window to the draw color. */ + SDL.RenderClear(renderer); + + /* put the newly-cleared rendering on the screen. */ + SDL.RenderPresent(renderer); + + return .Continue; /* carry on with the program! */ + } + + /* This function runs once at shutdown. */ + static void AppQuit(void *appstate, SDL.AppResult result) + { + /* SDL will clean up the window/renderer for us. */ + } + + public static int Main(String[] args) + { + char8*[] argv = scope .[args.Count]; + for (var arg in ref argv) + arg = args[@arg].Ptr; + return SDL.EnterAppMainCallbacks((.)argv.Count, argv.Ptr, => AppInit, => AppIterate, => AppEvent, => AppQuit); + } +} \ No newline at end of file diff --git a/SDL b/SDL new file mode 160000 index 0000000..c20a058 --- /dev/null +++ b/SDL @@ -0,0 +1 @@ +Subproject commit c20a058ff431d046c5806bd22aba0835b25d9904 diff --git a/Setup/.gitignore b/Setup/.gitignore new file mode 100644 index 0000000..99c45b3 --- /dev/null +++ b/Setup/.gitignore @@ -0,0 +1,5 @@ +build +recovery +BeefSpace_User.toml +BeefSpace_Lock.toml +SDL3_all.h \ No newline at end of file diff --git a/Setup/BeefProj.toml b/Setup/BeefProj.toml new file mode 100644 index 0000000..16fd960 --- /dev/null +++ b/Setup/BeefProj.toml @@ -0,0 +1,66 @@ +FileVersion = 1 +Dependencies = {corlib = "*", "Cpp2Beef.git" = {Git = "https://git.unicon-gmbh.de/BeefBindings/Cpp2Beef.git"}} + +[Project] +Name = "SDL3.Setup" +StartupObject = "SDL3.Setup.Program" + +[Configs.Debug.Win32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Debug.Win64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/CxxBuilderPath.txt $(WorkspaceDir)/../CxxBuilderPath.txt"] + +[Configs.Debug.Linux32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Debug.Linux64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Debug.macOS] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Release.Win32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Release.Win64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Release.Linux32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Release.Linux64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Release.macOS] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Paranoid.Win32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Paranoid.Win64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Paranoid.Linux32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Paranoid.Linux64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Paranoid.macOS] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Test.Win32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Test.Win64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Test.Linux32] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Test.Linux64] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] + +[Configs.Test.macOS] +PostBuildCmds = ["cp $(ProjectDir Cpp2Beef)/CxxBuilder/dist/SetCxxBuilderExe.beefscript $(WorkspaceDir)/../SetCxxBuilderExe.beefscript"] diff --git a/Setup/BeefSpace.toml b/Setup/BeefSpace.toml new file mode 100644 index 0000000..5cff17f --- /dev/null +++ b/Setup/BeefSpace.toml @@ -0,0 +1,6 @@ +FileVersion = 1 +Projects = {"SDL3.Setup" = {Path = "."}, "Clang-C.git" = {Git = "https://git.unicon-gmbh.de/BeefBindings/Clang-C.git"}, "Cpp2Beef.git" = {Git = "https://git.unicon-gmbh.de/BeefBindings/Cpp2Beef.git"}} +ExtraPlatforms = ["Linux32", "Linux64", "macOS"] + +[Workspace] +StartupProject = "SDL3.Setup" diff --git a/Setup/src/Program.bf b/Setup/src/Program.bf new file mode 100644 index 0000000..2ffbcf8 --- /dev/null +++ b/Setup/src/Program.bf @@ -0,0 +1,353 @@ +using System; +using System.IO; +using System.Collections; +using System.Diagnostics; + +using Cpp2Beef; +using LibClang; + +namespace SDL3.Setup; + +class SDL3Generator : Cpp2BeefGenerator, this(Span args) +{ + protected override Span Args => args; + protected override Flags Flags => .None; + + private BumpAllocator alloc = new .() ~ delete _; + + append Dictionary writers = .(16); + protected override StreamWriter GetWriterForHeader(StringView header) + { + String filename = Path.GetFileNameWithoutExtension(header, ..scope .(64)); + if (!filename.StartsWith("SDL_") || filename == "SDL_begin_code") return null; + if (writers.TryAdd(filename, let keyPtr, let valuePtr)) + { + *keyPtr = new:alloc .(filename); + *valuePtr = new:alloc .()..Create(scope $"../src/{filename}.bf")..Write(""" + // This file was generated by Cpp2Beef + + using System; + using System.Interop; + using static SDL3.SDL; + + namespace SDL3; + + + """); + } + return *valuePtr; + } + + protected override Block GetCursorBlock(CXCursor cursor) + { + if (Path.GetFileName(GetFilePath!(fileInfo.file), ..scope .(128)).StartsWith("SDL_test")) + return .CustomBlock("SDLTest"); + return .CustomBlock("SDL"); + } + + protected override void HandleCursor(CXCursor cursor) + { + switch (cursor.kind) + { + case .MacroDefinition: + if (Clang.Cursor_IsMacroFunctionLike(cursor) != 0 && GetFilePath!(fileInfo.file).EndsWith("SDL_version.h")) + { + BeginCursor(cursor); + let tokens = ScopeTokenize!(cursor, unit); + WriteCustomAttributes(cursor); + str.Append("public static "); + if (GetCursorSpelling!(cursor) == "SDL_VERSION_ATLEAST") + str.Append("bool "); + else + str.Append("c_int "); + GetNameInBindings(cursor, str); + bool inArgs = true; + for (let token in tokens[1...]) + { + if (inArgs) + { + let spelling = GetTokenSpelling!(token); + if (spelling == ")") + { + inArgs = false; + str.Append(") => "); + continue; + } + if (Clang.GetTokenKind(token) == .Identifier) + str.Append("c_int "); + str.Append(spelling); + if (spelling == ",") + str.Append(' '); + } + else + WriteToken(token); + } + str.Append(';'); + return; + } + + let spelling = GetCursorSpelling!(cursor); + if (spelling.StartsWith("SDL_PRI") || spelling.StartsWith("VK_DEFINE_")) + return; + switch (spelling) + { + case "FONT_LINE_HEIGHT": + BeginCursor(cursor); + str.Append("public static c_int FONT_LINE_HEIGHT => (FONT_CHARACTER_SIZE + 2);"); + return; + case "PFN_xrGetInstanceProcAddr": + BeginCursor(cursor); + str.Append("public typealias PFN_xrGetInstanceProcAddr = SDL.FunctionPointer;"); + return; + case "main", "SDL_SIZE_MAX", "SDL_FUNCTION", "SDL_FILE", "SDL_ASSERT_FILE", "SDL_LINE", "SDL_SCOPED_CAPABILITY", "SDL_NO_THREAD_SAFETY_ANALYSIS": + return; + } + case .TypedefDecl: + String prefix = scope .(64); + var spelling = GetCursorSpelling!(cursor); + + if (spelling == "SDL_Keycode") + prefix.Set("SDLK_"); + else + { + if (!spelling.StartsWith("SDL_")) fallthrough; + spelling.RemoveFromStart(4); + + /*if (GetTypeSpelling!(Clang.GetTypedefDeclUnderlyingType(cursor)) != "Uint32") + fallthrough;*/ + + if (spelling == "TrayEntryFlags") + spelling = "Trayentry"; + else if (spelling == "MouseButtonFlags") + spelling = "Button"; + else if (spelling.EndsWith("Flags")) + spelling.RemoveFromEnd(5); + else if (spelling.EndsWith("Flag")) + spelling.RemoveFromEnd(4); + /*else if (spelling.EndsWith("ID")) + spelling.RemoveFromEnd(2);*/ + else if (spelling == "BlendMode") + spelling = "Blendmode"; + else if (spelling == "GLContextResetNotification") + spelling = "GlContextReset"; + else if (spelling == "GLProfile") + spelling = "GlContextProfile"; + else if (spelling == "Keycode") + spelling = "K"; + else if (spelling != "GPUShaderFormat") + fallthrough; + if (spelling.StartsWith("GL")) + { + spelling = scope:: String(spelling); + spelling[1] = 'l'; + } + + prefix.Append("SDL"); + if (spelling.StartsWith("GPU")) + { + prefix.Append("_GPU_"); + for (let c in spelling[3...]) + prefix.Append(c.ToUpper); + prefix.Append('_'); + } + else + { + for (let c in spelling) + { + if (c.IsUpper) prefix.Append('_'); + prefix.Append(c.ToUpper); + } + prefix.Append('_'); + } + } + + BeginCursor(cursor); + if (spelling == "Button") str.Append("[AllowDuplicates] "); + AccessSpecifier(cursor); + str.Append("enum "); + GetNameInBindings(cursor, str); + str.Append(" : "); + Type(Clang.GetTypedefDeclUnderlyingType(cursor)); + void FixCurly() + { + if (fileInfo.queuedTokens.HasFlag(.LSquirly)) + str.Append("\n{"); + if (fileInfo.queuedTokens.HasFlag(.RSquirly)) + str.Append("\n}"); + else + str.Append("\n\t"); + fileInfo.queuedTokens = .None; + } + bool isSDL_GLContextFlag = spelling == "GlContext"; + { + BeginBody!(cursor); + for (let macro in this.[Friend]unitMacros) + { + let macroCursor = macro.value; + if (Clang.Cursor_IsMacroFunctionLike(macroCursor) != 0) + continue; + if (Clang.GetFileLocation(Clang.GetCursorLocation(macroCursor), ..?, ?, ?, ?) != fileInfo.file) + continue; + var macroSpelling = GetCursorSpelling!(macroCursor); + if (!macroSpelling.StartsWith(prefix)) + continue; + if (isSDL_GLContextFlag) + { + if (!macroSpelling.EndsWith("_FLAG")) + continue; + macroSpelling.RemoveFromEnd(5); + } + macroSpelling.RemoveFromStart(prefix.Length); + BeginCursor(macroCursor); + FixCurly(); + if (macroSpelling[0].IsDigit) str.Append('_'); + UpperSnakeCase2PascalCase(macroSpelling, str); + let tokens = ScopeTokenize!(macroCursor, unit); + AllWhiteSpaceBetween(Clang.GetRangeEnd(Clang.GetTokenExtent(unit, tokens[0])), Clang.GetRangeStart(Clang.GetTokenExtent(unit, tokens[1]))); + str.Append("= "); + WriteTokens(tokens[1...], Clang.GetNullLocation(), .Punctuation); + str.Append(','); + @macro.Remove(); + WriteComments(Clang.GetCursorLocation(macroCursor)); + } + } + FixCurly(); + return; + default: + } + base.HandleCursor(cursor); + } + + protected override void GetNameInBindings(CXCursor cursor, String outString) + { + bool RemovePrefix(ref StringView view) + { + if (view.StartsWith("SDLTest_")) view.RemoveFromStart(8); + else if (view.StartsWith("SDL_")) view.RemoveFromStart(4); + else return false; + return true; + } + + var spelling = GetCursorSpelling!(cursor); + if (!RemovePrefix(ref spelling)) + { + if (cursor.kind == .MacroDefinition) + switch (spelling) + { + case "NULL": outString.Append("null"); return; + case "TRUE": outString.Append("true"); return; + case "FALSE": outString.Append("false"); return; + } + base.GetNameInBindings(cursor, outString); + return; + } + switch (cursor.kind) + { + case .EnumConstantDecl: + var parentSpelling = GetCursorSpelling!(Clang.GetCursorSemanticParent(cursor)); + if (parentSpelling == "SDL_GPUTextureFormat") + { + spelling.RemoveFromStart("GPU_TEXTUREFORMAT_".Length); + outString.Append(spelling); + break; + } + + StringView name = UpperSnakeCase2PascalCase(spelling, ..scope .(spelling.Length)); + switch (parentSpelling) + { + case "SDL_AudioFormat": parentSpelling = "Audio"; + case "SDL_AssertState": parentSpelling = "Assertion"; + case "SDL_GamepadBindingType": parentSpelling = "GamepadBindtype"; + case "SDL_RendererLogicalPresentation": parentSpelling = "LogicalPresentation"; + default: + RemovePrefix(ref parentSpelling); + } + for (let c in parentSpelling) + { + if (name[0].ToLower == c.ToLower) + name.RemoveFromStart(1); + else + break; + } + if (name[0].IsDigit) + outString.Append('_'); + outString.Append(name); + default: + outString.Append(spelling); + } + } + + protected override void WriteToken(CXToken token) + { + var spelling = GetTokenSpelling!(token); + switch (spelling) + { + case "size_t": str.Append("c_size"); return; + case "SDL_BUTTON_LEFT": str.Append("Left"); return; + case "SDL_BUTTON_MIDDLE": str.Append("Middle"); return; + case "SDL_BUTTON_RIGHT": str.Append("Right"); return; + case "SDL_BUTTON_X1": str.Append("X1"); return; + case "SDL_BUTTON_X2": str.Append("X2"); return; + } + if (!spelling.StartsWith("SDL_") || !spelling.EndsWith("ID")) + { + base.WriteToken(token); + return; + } + spelling.RemoveFromStart(4); + str.Append("SDL."); + str.Append(spelling); + } + + protected override bool IsOutParam(CXCursor arg, CXCursor method) + { + let comment = Clang.Cursor_GetParsedComment(method); + let spelling = GetCursorSpelling!(arg); + for (let i < Clang.Comment_GetNumChildren(comment)) + { + let param = Clang.Comment_GetChild(comment, i); + if (Clang.Comment_GetKind(param) != .ParamCommand || + ScopeCXString!(Clang.ParamCommandComment_GetParamName(param)) != spelling) continue; + let paragraph = Clang.BlockCommandComment_GetParagraph(param); + if (Clang.Comment_GetNumChildren(paragraph) == 0) continue; + let paragraphChild = Clang.Comment_GetChild(paragraph, 0); + if (Clang.Comment_GetKind(paragraphChild) != .Text) continue; + StringView paragraphText = ScopeCXString!(Clang.TextComment_GetText(paragraphChild))..TrimStart(); + if (paragraphText.StartsWith("a pointer filled in") || paragraphText.StartsWith("a pointer to receive")) return true; + else break; + } + return base.IsOutParam(arg, method); + } +} + +class Program +{ + [CLink] static extern int32 system(char8*); + + public static int Main(String[] args) + { + //Runtime.Assert(system("git -C .. submodule update") == 0, "Failed to fetch SDL3, check your internet connection"); + + { + StreamWriter all = scope .()..Create("SDL3_all.h"); + for (let file in Directory.EnumerateFiles("../SDL/include/SDL3")) + { + let filename = file.GetFileName(..scope .(64)); + if (filename == "SDL_oldnames.h" || filename == "SDL_egl.h" || filename == "SDL_intrin.h" || filename == "SDL_endian.h" || + filename == "SDL_platform_defines.h" || filename == "SDL_begin_code.h" || filename == "SDL_close_code.h" || filename.StartsWith("SDL_opengl")) + continue; + all.Write("#include \n"); + } + } + + SDL3Generator generator = scope .(char8*[?]("--language=c", "-I../SDL/include", + "-DSDL_oldnames_h_", "-DSDL_platform_defines_h_", "-DSDL_endian_h_", + "-DCrcUint32=Uint32", "-DCrcUint8=Uint8", + "-DSDL_SLOW_MEMCPY", "-DSDL_SLOW_MEMMOVE", "-DSDL_SLOW_MEMSET", "-DSDL_DISABLE_ALLOCA", "-DSDL_DISABLE_ANALYZE_MACROS")); + generator.Generate("SDL3_all.h", null); + + return 0; + } +} \ No newline at end of file diff --git a/src/Library.bf b/src/Library.bf new file mode 100644 index 0000000..0c29e97 --- /dev/null +++ b/src/Library.bf @@ -0,0 +1,19 @@ +using System; + +namespace SDL3; + +static class SDL +{ + private static Sint64 SINT64_C(Sint64 n) => n; + private static Uint64 UINT64_C(Uint64 n) => n; + + typealias CrcUint32 = Uint32; + typealias CrcUint8 = Uint8; + + private static Uint32 BUTTON_MASK(MouseButtonFlags X) => (.)(1u << (((Uint32)X)-1)); +} + +static class SDLTest +{ + +} diff --git a/src/SDL_assert.bf b/src/SDL_assert.bf new file mode 100644 index 0000000..ab52c5f --- /dev/null +++ b/src/SDL_assert.bf @@ -0,0 +1,701 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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! + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + + + +/** + * 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. + */ + + + + + + + + + +public const let ASSERT_LEVEL = 1; + + + + + +/** + * 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. + */ + + + + /* Don't include intrin.h here because it contains C++ code */ + [CLink] public static extern void __debugbreak(); + + + + + + + + + + + +/* this might work on other ARM targets, but this is a known quantity... */ + + + + + + + /* older gcc may not support SDL_HAS_BUILTIN(__builtin_trap) above */ + + + + + + + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ + + + + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ + + +/* C99 supports __func__ as a standard. */ + + + + + + + + + +/** + * 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. + */ + + + + + + + + + + + + +/** + * 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. + */ + + + + + + + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ + + +/* +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. +*/ + + + +/** + * 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. + */ + + +/* 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! */ +public const let NULL_WHILE_LOOP_CONDITION = (0,0); + + + + +/** + * 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. + */ + + + +/** + * 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. + */ +[AllowDuplicates] public enum AssertState : c_int +{ + Retry, /**< Retry the assert immediately. */ + Break, /**< Make the debugger trigger a breakpoint. */ + Abort, /**< Terminate the program. */ + Ignore, /**< Ignore the assert. */ + AlwaysIgnore, /**< Ignore the assert from now on. */ +} + +/** + * 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. + */ +[CRepr] public struct AssertData +{ + public bool always_ignore; /**< true if app should always continue when assertion is triggered. */ + public c_uint trigger_count; /**< Number of times this assertion has been triggered. */ + public c_char* condition; /**< A string of this assert's test code. */ + public c_char* filename; /**< The source file where this assert lives. */ + public c_int linenum; /**< The line in `filename` where this assert lives. */ + public c_char* @function; /**< The name of the function where this assert lives. */ + public AssertData* next; /**< next item in the linked list. */ +} + +/** + * 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. + */ +[LinkName("SDL_ReportAssertion")] public static extern AssertState ReportAssertion(AssertData* data, c_char* func, c_char* file, c_int line); + + + + +/** + * 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 this as empty in case assert() is defined as SDL_assert */ + + + + +/* !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. + */ + + + + + + + /* go again. */ + + + + /* not retrying. */ + + + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/* Enable various levels of assertions. */ +/* assertions disabled */ + + + +/* release settings. */ + + + +/* debug settings. */ + + + +/* paranoid settings. */ + + + + + + + +/** + * 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. + */ + + + +/** + * 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. + */ +public function AssertState AssertionHandler(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 + */ +[LinkName("SDL_SetAssertionHandler")] public static extern void SetAssertionHandler(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 + */ +[LinkName("SDL_GetDefaultAssertionHandler")] public static extern AssertionHandler GetDefaultAssertionHandler(); + +/** + * 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 + */ +[LinkName("SDL_GetAssertionHandler")] public static extern AssertionHandler 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 + */ +[LinkName("SDL_GetAssertionReport")] public static extern AssertData* GetAssertionReport(); + +/** + * 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 + */ +[LinkName("SDL_ResetAssertionReport")] public static extern void ResetAssertionReport(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_assert_h_ */ \ No newline at end of file diff --git a/src/SDL_asyncio.bf b/src/SDL_asyncio.bf new file mode 100644 index 0000000..1e87ac6 --- /dev/null +++ b/src/SDL_asyncio.bf @@ -0,0 +1,557 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[CRepr] public struct AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum AsyncIOTaskType : c_int +{ + Read, /**< A read operation. */ + Write, /**< A write operation. */ + Close, /**< A close operation. */ +} + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum AsyncIOResult : c_int +{ + Complete, /**< request was completed without error */ + Failure, /**< request failed for some reason; check SDL_GetError()! */ + Canceled, /**< request was canceled before completing. */ +} + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct AsyncIOOutcome +{ + public AsyncIO* asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + public AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + public AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + public void* buffer; /**< buffer where data was read/written. */ + public Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + public Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + public Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + public void* userdata; /**< pointer provided by the app when starting the task */ +} + +/** + * 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 + */ +[CRepr] public struct AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +[LinkName("SDL_AsyncIOFromFile")] public static extern AsyncIO* AsyncIOFromFile(c_char* file, c_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. + */ +[LinkName("SDL_GetAsyncIOSize")] public static extern Sint64 GetAsyncIOSize(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 + */ +[LinkName("SDL_ReadAsyncIO")] public static extern bool ReadAsyncIO(AsyncIO* asyncio, void* ptr, Uint64 offset, Uint64 size, 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 + */ +[LinkName("SDL_WriteAsyncIO")] public static extern bool WriteAsyncIO(AsyncIO* asyncio, void* ptr, Uint64 offset, Uint64 size, 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. + */ +[LinkName("SDL_CloseAsyncIO")] public static extern bool CloseAsyncIO(AsyncIO* asyncio, bool flush, 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 + */ +[LinkName("SDL_CreateAsyncIOQueue")] public static extern AsyncIOQueue* CreateAsyncIOQueue(); + +/** + * 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. + */ +[LinkName("SDL_DestroyAsyncIOQueue")] public static extern void DestroyAsyncIOQueue(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 + */ +[LinkName("SDL_GetAsyncIOResult")] public static extern bool GetAsyncIOResult(AsyncIOQueue* queue, 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 + */ +[LinkName("SDL_WaitAsyncIOResult")] public static extern bool WaitAsyncIOResult(AsyncIOQueue* queue, 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 + */ +[LinkName("SDL_SignalAsyncIOQueue")] public static extern void SignalAsyncIOQueue(AsyncIOQueue* queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +[LinkName("SDL_LoadFileAsync")] public static extern bool LoadFileAsync(c_char* file, AsyncIOQueue* queue, void* userdata); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_asyncio_h_ */ \ No newline at end of file diff --git a/src/SDL_atomic.bf b/src/SDL_atomic.bf new file mode 100644 index 0000000..377e22b --- /dev/null +++ b/src/SDL_atomic.bf @@ -0,0 +1,693 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias SpinLock = c_int; + +/** + * 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 + */ +[LinkName("SDL_TryLockSpinlock")] public static extern bool TryLockSpinlock(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 + */ +[LinkName("SDL_LockSpinlock")] public static extern void LockSpinlock(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 + */ +[LinkName("SDL_UnlockSpinlock")] public static extern void UnlockSpinlock(SpinLock* lock); + + + + +/** + * 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. + */ + + + + + + + +/* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */ + + + + + + + + + +/** + * 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 + */ +[LinkName("SDL_MemoryBarrierReleaseFunction")] public static extern void MemoryBarrierReleaseFunction(); + +/** + * 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 + */ +[LinkName("SDL_MemoryBarrierAcquireFunction")] public static extern void MemoryBarrierAcquireFunction(); + + + + +/** + * 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 + */ + + +/** + * 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 + */ + + + + + + + + + +/* 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 +*/ + + + + + + + + + +/* The mcr instruction isn't available in thumb mode, use real functions */ + + + + + + +/* __thumb__ */ + + + +/* SDL_PLATFORM_LINUX || SDL_PLATFORM_ANDROID */ +/* __GNUC__ && __arm__ */ + + +/* This is correct for all CPUs on Solaris when using Solaris Studio 12.1+. */ + + + + +/* This is correct for the x86 and x64 CPUs, and we'll expand this over time. */ + + + + + +/* "REP NOP" is PAUSE, coded for tools that don't know it by that name. */ + + +/** + * 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. + */ + + + + /* Some assemblers can't do REP NOP, so go with PAUSE. */ + + + + + + + + /* this is actually "rep nop" and not a SIMD instruction. No inline asm in MSVC x86-64! */ + + + + + + + + + + +/** + * 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 + */ +[CRepr] public struct AtomicInt { public c_int value; } + +/** + * 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 + */ +[LinkName("SDL_CompareAndSwapAtomicInt")] public static extern bool CompareAndSwapAtomicInt(AtomicInt* a, c_int oldval, c_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 + */ +[LinkName("SDL_SetAtomicInt")] public static extern c_int SetAtomicInt(AtomicInt* a, c_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 + */ +[LinkName("SDL_GetAtomicInt")] public static extern c_int GetAtomicInt(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 + */ +[LinkName("SDL_AddAtomicInt")] public static extern c_int AddAtomicInt(AtomicInt* a, c_int v); + + + +/** + * 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 + */ + + + + + +/** + * 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 + */ + + + +/** + * 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 + */ +[CRepr] public struct AtomicU32 { public Uint32 value; } + +/** + * 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 + */ +[LinkName("SDL_CompareAndSwapAtomicU32")] public static extern bool CompareAndSwapAtomicU32(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 + */ +[LinkName("SDL_SetAtomicU32")] public static extern Uint32 SetAtomicU32(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 + */ +[LinkName("SDL_GetAtomicU32")] public static extern Uint32 GetAtomicU32(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. + */ +[LinkName("SDL_AddAtomicU32")] public static extern Uint32 AddAtomicU32(AtomicU32* a, c_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 + */ +[LinkName("SDL_CompareAndSwapAtomicPointer")] public static extern bool 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 + */ +[LinkName("SDL_SetAtomicPointer")] public static extern void* 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 + */ +[LinkName("SDL_GetAtomicPointer")] public static extern void* GetAtomicPointer(void** a); +} + +/* Ends C function definitions when using C++ */ + + + + + + +/* SDL_atomic_h_ */ \ No newline at end of file diff --git a/src/SDL_audio.bf b/src/SDL_audio.bf new file mode 100644 index 0000000..327e092 --- /dev/null +++ b/src/SDL_audio.bf @@ -0,0 +1,2367 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ + + + +/** + * 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 + */ +[AllowDuplicates] public enum AudioFormat : c_int +{ + Unknown = 0x0000u, /**< Unspecified audio format */ + U8 = 0x0008u, /**< Unsigned 8-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */ + S8 = 0x8008u, /**< Signed 8-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */ + S16le = 0x8010u, /**< Signed 16-bit samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */ + S16be = 0x9010u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */ + S32le = 0x8020u, /**< 32-bit integer samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */ + S32be = 0x9020u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */ + F32le = 0x8120u, /**< 32-bit floating point samples */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ + F32be = 0x9120u, /**< As above, but big-endian byte order */ + /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ + + /* These represent the current system's byteorder. */ + + S16 = S16le, + S32 = S32le, + F32 = F32le, + + + + + +} + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + + +/** + * SDL Audio Device instance IDs. + * + * Zero is used to signify an invalid/null device. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias AudioDeviceID = Uint32; + +/** + * 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. + */ +public const let 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. + */ +public const let 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 + */ +[CRepr] public struct AudioSpec +{ + public AudioFormat format; /**< Audio data format */ + public c_int channels; /**< Number of channels: 1 mono, 2 stereo, etc */ + public c_int freq; /**< sample rate: sample frames per second */ +} + +/** + * 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. + */ + + +/** + * The opaque handle that represents an audio stream. + * + * SDL_AudioStream is an audio conversion interface. + * + * - It can handle resampling data in chunks without generating artifacts, + * when it doesn't have the complete buffer available. + * - It can handle incoming data in any variable size. + * - It can handle input/output format changes on the fly. + * - It can remap audio channels between inputs and outputs. + * - You push data as you have it, and pull it when you need it + * - It can also function as a basic audio data queue even if you just have + * sound that needs to pass from one place to another. + * - You can hook callbacks up to them when more data is added or requested, + * to manage data on-the-fly. + * + * Audio streams are the core of the SDL3 audio interface. You create one or + * more of them, bind them to an opened audio device, and feed data to them + * (or for recording, consume data from them). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAudioStream + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_GetNumAudioDrivers")] public static extern c_int GetNumAudioDrivers(); + +/** + * 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 + */ +[LinkName("SDL_GetAudioDriver")] public static extern c_char* GetAudioDriver(c_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. + */ +[LinkName("SDL_GetCurrentAudioDriver")] public static extern c_char* GetCurrentAudioDriver(); + +/** + * 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 + */ +[LinkName("SDL_GetAudioPlaybackDevices")] public static extern AudioDeviceID* GetAudioPlaybackDevices(out c_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 + */ +[LinkName("SDL_GetAudioRecordingDevices")] public static extern AudioDeviceID* GetAudioRecordingDevices(out c_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 + */ +[LinkName("SDL_GetAudioDeviceName")] public static extern c_char* GetAudioDeviceName(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. + */ +[LinkName("SDL_GetAudioDeviceFormat")] public static extern bool GetAudioDeviceFormat(AudioDeviceID devid, AudioSpec* spec, c_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 + */ +[LinkName("SDL_GetAudioDeviceChannelMap")] public static extern c_int* GetAudioDeviceChannelMap(AudioDeviceID devid, c_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 + */ +[LinkName("SDL_OpenAudioDevice")] public static extern AudioDeviceID OpenAudioDevice(AudioDeviceID devid, 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. + */ +[LinkName("SDL_IsAudioDevicePhysical")] public static extern bool IsAudioDevicePhysical(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. + */ +[LinkName("SDL_IsAudioDevicePlayback")] public static extern bool IsAudioDevicePlayback(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 + */ +[LinkName("SDL_PauseAudioDevice")] public static extern bool PauseAudioDevice(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 + */ +[LinkName("SDL_ResumeAudioDevice")] public static extern bool ResumeAudioDevice(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 + */ +[LinkName("SDL_AudioDevicePaused")] public static extern bool AudioDevicePaused(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 + */ +[LinkName("SDL_GetAudioDeviceGain")] public static extern float GetAudioDeviceGain(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 + */ +[LinkName("SDL_SetAudioDeviceGain")] public static extern bool SetAudioDeviceGain(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 + */ +[LinkName("SDL_CloseAudioDevice")] public static extern void CloseAudioDevice(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 + */ +[LinkName("SDL_BindAudioStreams")] public static extern bool BindAudioStreams(AudioDeviceID devid, AudioStream** streams, c_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 + */ +[LinkName("SDL_BindAudioStream")] public static extern bool BindAudioStream(AudioDeviceID devid, 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 + */ +[LinkName("SDL_UnbindAudioStreams")] public static extern void UnbindAudioStreams(AudioStream** streams, c_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 + */ +[LinkName("SDL_UnbindAudioStream")] public static extern void UnbindAudioStream(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 + */ +[LinkName("SDL_GetAudioStreamDevice")] public static extern AudioDeviceID GetAudioStreamDevice(AudioStream* stream); + +/** + * Create a new audio stream. + * + * \param src_spec the format details of the input audio. + * \param dst_spec the format details of the output audio. + * \returns a new audio stream on success or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PutAudioStreamData + * \sa SDL_GetAudioStreamData + * \sa SDL_GetAudioStreamAvailable + * \sa SDL_FlushAudioStream + * \sa SDL_ClearAudioStream + * \sa SDL_SetAudioStreamFormat + * \sa SDL_DestroyAudioStream + */ +[LinkName("SDL_CreateAudioStream")] public static extern AudioStream* CreateAudioStream(AudioSpec* src_spec, 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. + */ +[LinkName("SDL_GetAudioStreamProperties")] public static extern PropertiesID GetAudioStreamProperties(AudioStream* stream); + +public const let 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 + */ +[LinkName("SDL_GetAudioStreamFormat")] public static extern bool GetAudioStreamFormat(AudioStream* stream, AudioSpec* src_spec, AudioSpec* dst_spec); + +/** + * Change the input and output formats of an audio stream. + * + * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData + * will reflect the new format, and future calls to SDL_PutAudioStreamData + * must provide data in the new input formats. + * + * Data that was previously queued in the stream will still be operated on in + * the format that was current when it was added, which is to say you can put + * the end of a sound file in one format to a stream, change formats for the + * next sound file, and start putting that new data while the previous sound + * file is still queued, and everything will still play back correctly. + * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * + * \param stream the stream the format is being changed. + * \param src_spec the new format of the audio input; if NULL, it is not + * changed. + * \param dst_spec the new format of the audio output; if NULL, it is not + * changed. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, as it holds + * a stream-specific mutex while running. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAudioStreamFormat + * \sa SDL_SetAudioStreamFrequencyRatio + */ +[LinkName("SDL_SetAudioStreamFormat")] public static extern bool SetAudioStreamFormat(AudioStream* stream, AudioSpec* src_spec, 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 + */ +[LinkName("SDL_GetAudioStreamFrequencyRatio")] public static extern float GetAudioStreamFrequencyRatio(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 + */ +[LinkName("SDL_SetAudioStreamFrequencyRatio")] public static extern bool SetAudioStreamFrequencyRatio(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 + */ +[LinkName("SDL_GetAudioStreamGain")] public static extern float GetAudioStreamGain(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 + */ +[LinkName("SDL_SetAudioStreamGain")] public static extern bool SetAudioStreamGain(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 + */ +[LinkName("SDL_GetAudioStreamInputChannelMap")] public static extern c_int* GetAudioStreamInputChannelMap(AudioStream* stream, c_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 + */ +[LinkName("SDL_GetAudioStreamOutputChannelMap")] public static extern c_int* GetAudioStreamOutputChannelMap(AudioStream* stream, c_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 + */ +[LinkName("SDL_SetAudioStreamInputChannelMap")] public static extern bool SetAudioStreamInputChannelMap(AudioStream* stream, c_int* chmap, c_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 + */ +[LinkName("SDL_SetAudioStreamOutputChannelMap")] public static extern bool SetAudioStreamOutputChannelMap(AudioStream* stream, c_int* chmap, c_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 + */ +[LinkName("SDL_PutAudioStreamData")] public static extern bool PutAudioStreamData(AudioStream* stream, void* buf, c_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 + */ +public function void AudioStreamDataCompleteCallback(void* userdata, void* buf, c_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 + */ +[LinkName("SDL_PutAudioStreamDataNoCopy")] public static extern bool PutAudioStreamDataNoCopy(AudioStream* stream, void* buf, c_int len, 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 + */ +[LinkName("SDL_PutAudioStreamPlanarData")] public static extern bool PutAudioStreamPlanarData(AudioStream* stream, void** channel_buffers, c_int num_channels, c_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 + */ +[LinkName("SDL_GetAudioStreamData")] public static extern c_int GetAudioStreamData(AudioStream* stream, void* buf, c_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 + */ +[LinkName("SDL_GetAudioStreamAvailable")] public static extern c_int GetAudioStreamAvailable(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 + */ +[LinkName("SDL_GetAudioStreamQueued")] public static extern c_int GetAudioStreamQueued(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 + */ +[LinkName("SDL_FlushAudioStream")] public static extern bool FlushAudioStream(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 + */ +[LinkName("SDL_ClearAudioStream")] public static extern bool ClearAudioStream(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 + */ +[LinkName("SDL_PauseAudioStreamDevice")] public static extern bool PauseAudioStreamDevice(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 + */ +[LinkName("SDL_ResumeAudioStreamDevice")] public static extern bool ResumeAudioStreamDevice(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 + */ +[LinkName("SDL_AudioStreamDevicePaused")] public static extern bool AudioStreamDevicePaused(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 + */ +[LinkName("SDL_LockAudioStream")] public static extern bool LockAudioStream(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 + */ +[LinkName("SDL_UnlockAudioStream")] public static extern bool UnlockAudioStream(AudioStream* stream); + +/** + * A callback that fires when data passes through an SDL_AudioStream. + * + * Apps can (optionally) register a callback with an audio stream that is + * called when data is added with SDL_PutAudioStreamData, or requested with + * SDL_GetAudioStreamData. + * + * Two values are offered here: one is the amount of additional data needed to + * satisfy the immediate request (which might be zero if the stream already + * has enough data queued) and the other is the total amount being requested. + * In a Get call triggering a Put callback, these values can be different. In + * a Put call triggering a Get callback, these values are always the same. + * + * Byte counts might be slightly overestimated due to buffering or resampling, + * and may change from call to call. + * + * This callback is not required to do anything. Generally this is useful for + * adding/reading data on demand, and the app will often put/get data as + * appropriate, but the system goes on with the data currently available to it + * if this callback does nothing. + * + * \param stream the SDL audio stream associated with this callback. + * \param additional_amount the amount of data, in bytes, that is needed right + * now. + * \param total_amount the total amount of data requested, in bytes, that is + * requested or available. + * \param userdata an opaque pointer provided by the app for their personal + * use. + * + * \threadsafety This callbacks may run from any thread, so if you need to + * protect shared data, you should use SDL_LockAudioStream to + * serialize access; this lock will be held before your callback + * is called, so your callback does not need to manage the lock + * explicitly. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetAudioStreamGetCallback + * \sa SDL_SetAudioStreamPutCallback + */ +public function void AudioStreamCallback(void* userdata, AudioStream* stream, c_int additional_amount, c_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 + */ +[LinkName("SDL_SetAudioStreamGetCallback")] public static extern bool SetAudioStreamGetCallback(AudioStream* stream, 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 + */ +[LinkName("SDL_SetAudioStreamPutCallback")] public static extern bool SetAudioStreamPutCallback(AudioStream* stream, 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 + */ +[LinkName("SDL_DestroyAudioStream")] public static extern void DestroyAudioStream(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 + */ +[LinkName("SDL_OpenAudioDeviceStream")] public static extern AudioStream* OpenAudioDeviceStream(AudioDeviceID devid, AudioSpec* spec, 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 + */ +public function void AudioPostmixCallback(void* userdata, AudioSpec* spec, float* buffer, c_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. + */ +[LinkName("SDL_SetAudioPostmixCallback")] public static extern bool SetAudioPostmixCallback(AudioDeviceID devid, 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 + */ +[LinkName("SDL_LoadWAV_IO")] public static extern bool LoadWAV_IO(IOStream* src, bool closeio, 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 + */ +[LinkName("SDL_LoadWAV")] public static extern bool LoadWAV(c_char* path, 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. + */ +[LinkName("SDL_MixAudio")] public static extern bool MixAudio(Uint8* dst, Uint8* src, 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. + */ +[LinkName("SDL_ConvertAudioSamples")] public static extern bool ConvertAudioSamples(AudioSpec* src_spec, Uint8* src_data, c_int src_len, AudioSpec* dst_spec, Uint8** dst_data, c_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. + */ +[LinkName("SDL_GetAudioFormatName")] public static extern c_char* GetAudioFormatName(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. + */ +[LinkName("SDL_GetSilenceValueForFormat")] public static extern c_int GetSilenceValueForFormat(AudioFormat format); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_audio_h_ */ \ No newline at end of file diff --git a/src/SDL_bits.bf b/src/SDL_bits.bf new file mode 100644 index 0000000..5f3887a --- /dev/null +++ b/src/SDL_bits.bf @@ -0,0 +1,152 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryBits + * + * Functions for fiddling with bits and bitmasks. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + + + + + + + + + + +/** + * Get the index of the most significant (set) bit in a 32-bit number. + * + * Result is undefined when called with 0. This operation can also be stated + * as "count leading zeroes" and "log base 2". + * + * Note that this is a forced-inline function in a header, and not a public + * API function available in the SDL library (which is to say, the code is + * embedded in the calling program and the linker and dynamic loader will not + * be able to find this function inside SDL itself). + * + * \param x the 32-bit value to examine. + * \returns the index of the most significant bit, or -1 if the value is 0. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_MostSignificantBitIndex32")] public static extern c_int MostSignificantBitIndex32(Uint32 x); + + + /* Count Leading Zeroes builtin in GCC. + * http://gcc.gnu.org/onlinedocs/gcc-4.3.4/gcc/Other-Builtins.html + */ + + + + + + + + + + + + + + + + + /* Based off of Bit Twiddling Hacks by Sean Eron Anderson + * , released in the public domain. + * http://graphics.stanford.edu/~seander/bithacks.html#IntegerLog + */ + + + + + + + + + + + + + + + + + + + + + + + +/** + * 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. + */ +[LinkName("SDL_HasExactlyOneBitSet32")] public static extern bool HasExactlyOneBitSet32(Uint32 x); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_bits_h_ */ \ No newline at end of file diff --git a/src/SDL_blendmode.bf b/src/SDL_blendmode.bf new file mode 100644 index 0000000..afc9419 --- /dev/null +++ b/src/SDL_blendmode.bf @@ -0,0 +1,216 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryBlendmode + * + * 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +public enum BlendMode : Uint32 +{ + None = 0x00000000u, /**< no blending: dstRGBA = srcRGBA */ + Blend = 0x00000001u, /**< alpha blending: dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA)), dstA = srcA + (dstA * (1-srcA)) */ + BlendPremultiplied = 0x00000010u, /**< pre-multiplied alpha blending: dstRGBA = srcRGBA + (dstRGBA * (1-srcA)) */ + Add = 0x00000002u, /**< additive blending: dstRGB = (srcRGB * srcA) + dstRGB, dstA = dstA */ + AddPremultiplied = 0x00000020u, /**< pre-multiplied additive blending: dstRGB = srcRGB + dstRGB, dstA = dstA */ + Mod = 0x00000004u, /**< color modulate: dstRGB = srcRGB * dstRGB, dstA = dstA */ + Mul = 0x00000008u, /**< color multiply: dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA)), dstA = dstA */ + Invalid = 0x7FFFFFFFu, + +/** + * The blend operation used when combining source and destination pixel + * components. + * + * \since This enum is available since SDL 3.2.0. + */ +} + +/** + * The blend operation used when combining source and destination pixel + * components. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum BlendOperation : c_int +{ + Add = 0x1, /**< dst + src: supported by all renderers */ + Subtract = 0x2, /**< src - dst : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + RevSubtract = 0x3, /**< dst - src : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + Minimum = 0x4, /**< min(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */ + Maximum = 0x5, /**< max(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */ +} + +/** + * 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. + */ +[AllowDuplicates] public enum BlendFactor : c_int +{ + Zero = 0x1, /**< 0, 0, 0, 0 */ + One = 0x2, /**< 1, 1, 1, 1 */ + SrcColor = 0x3, /**< srcR, srcG, srcB, srcA */ + OneMinusSrcColor = 0x4, /**< 1-srcR, 1-srcG, 1-srcB, 1-srcA */ + SrcAlpha = 0x5, /**< srcA, srcA, srcA, srcA */ + OneMinusSrcAlpha = 0x6, /**< 1-srcA, 1-srcA, 1-srcA, 1-srcA */ + DstColor = 0x7, /**< dstR, dstG, dstB, dstA */ + OneMinusDstColor = 0x8, /**< 1-dstR, 1-dstG, 1-dstB, 1-dstA */ + DstAlpha = 0x9, /**< dstA, dstA, dstA, dstA */ + OneMinusDstAlpha = 0xA, /**< 1-dstA, 1-dstA, 1-dstA, 1-dstA */ +} + +/** + * Compose a custom blend mode for renderers. + * + * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept + * the SDL_BlendMode returned by this function if the renderer supports it. + * + * A blend mode controls how the pixels from a drawing operation (source) get + * combined with the pixels from the render target (destination). First, the + * components of the source and destination pixels get multiplied with their + * blend factors. Then, the blend operation takes the two products and + * calculates the result that will get stored in the render target. + * + * Expressed in pseudocode, it would look like this: + * + * ```c + * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor); + * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor); + * ``` + * + * Where the functions `colorOperation(src, dst)` and `alphaOperation(src, + * dst)` can return one of the following: + * + * - `src + dst` + * - `src - dst` + * - `dst - src` + * - `min(src, dst)` + * - `max(src, dst)` + * + * The red, green, and blue components are always multiplied with the first, + * second, and third components of the SDL_BlendFactor, respectively. The + * fourth component is not used. + * + * The alpha component is always multiplied with the fourth component of the + * SDL_BlendFactor. The other components are not used in the alpha + * calculation. + * + * Support for these blend modes varies for each renderer. To check if a + * specific SDL_BlendMode is supported, create a renderer and pass it to + * 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. + * 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 here. + * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`, + * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` + * operations with all factors. + * - **psp**: No custom blend mode support. + * - **software**: No custom blend mode support. + * + * Some renderers do not provide an alpha component for the default render + * target. The `SDL_BLENDFACTOR_DST_ALPHA` and + * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this + * case. + * + * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and + * blue components of the source pixels. + * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and + * blue components of the destination pixels. + * \param colorOperation the SDL_BlendOperation used to combine the red, + * green, and blue components of the source and + * destination pixels. + * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of + * the source pixels. + * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of + * the destination pixels. + * \param alphaOperation the SDL_BlendOperation used to combine the alpha + * component of the source and destination pixels. + * \returns an SDL_BlendMode that represents the chosen factors and + * operations. + * + * \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 + */ +[LinkName("SDL_ComposeCustomBlendMode")] public static extern BlendMode ComposeCustomBlendMode(BlendFactor srcColorFactor, BlendFactor dstColorFactor, BlendOperation colorOperation, BlendFactor srcAlphaFactor, BlendFactor dstAlphaFactor, BlendOperation alphaOperation); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_blendmode_h_ */ \ No newline at end of file diff --git a/src/SDL_camera.bf b/src/SDL_camera.bf new file mode 100644 index 0000000..2080b1e --- /dev/null +++ b/src/SDL_camera.bf @@ -0,0 +1,546 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +public typealias CameraID = Uint32; + +/** + * The opaque structure used to identify an opened SDL camera. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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 + */ +[CRepr] public struct CameraSpec +{ + public PixelFormat format; /**< Frame format */ + public Colorspace colorspace; /**< Frame colorspace */ + public c_int width; /**< Frame width */ + public c_int height; /**< Frame height */ + public c_int framerate_numerator; /**< Frame rate numerator ((num / denom) == FPS, (denom / num) == duration in seconds) */ + public c_int framerate_denominator; /**< Frame rate denominator ((num / denom) == FPS, (denom / num) == duration in seconds) */ +} + +/** + * The position of camera in relation to system device. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetCameraPosition + */ +[AllowDuplicates] public enum CameraPosition : c_int +{ + Unknown, + FrontFacing, + BackFacing, +} + +/** + * The current state of a request for camera access. + * + * \since This enum is available since SDL 3.4.0. + * + * \sa SDL_GetCameraPermissionState + */ +[AllowDuplicates] public enum CameraPermissionState : c_int +{ + Denied = -1, + Pending, + Approved, +} + + +/** + * 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 + */ +[LinkName("SDL_GetNumCameraDrivers")] public static extern c_int GetNumCameraDrivers(); + +/** + * 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 + */ +[LinkName("SDL_GetCameraDriver")] public static extern c_char* GetCameraDriver(c_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. + */ +[LinkName("SDL_GetCurrentCameraDriver")] public static extern c_char* GetCurrentCameraDriver(); + +/** + * 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 + */ +[LinkName("SDL_GetCameras")] public static extern CameraID* GetCameras(out c_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 + */ +[LinkName("SDL_GetCameraSupportedFormats")] public static extern CameraSpec** GetCameraSupportedFormats(CameraID instance_id, out c_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 + */ +[LinkName("SDL_GetCameraName")] public static extern c_char* GetCameraName(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 + */ +[LinkName("SDL_GetCameraPosition")] public static extern CameraPosition GetCameraPosition(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 + */ +[LinkName("SDL_OpenCamera")] public static extern Camera* OpenCamera(CameraID instance_id, 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 + */ +[LinkName("SDL_GetCameraPermissionState")] public static extern CameraPermissionState GetCameraPermissionState(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 + */ +[LinkName("SDL_GetCameraID")] public static extern CameraID GetCameraID(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. + */ +[LinkName("SDL_GetCameraProperties")] public static extern PropertiesID GetCameraProperties(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 + */ +[LinkName("SDL_GetCameraFormat")] public static extern bool GetCameraFormat(Camera* camera, 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 + */ +[LinkName("SDL_AcquireCameraFrame")] public static extern Surface* AcquireCameraFrame(Camera* camera, out 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 + */ +[LinkName("SDL_ReleaseCameraFrame")] public static extern void ReleaseCameraFrame(Camera* camera, 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 + */ +[LinkName("SDL_CloseCamera")] public static extern void CloseCamera(Camera* camera); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_camera_h_ */ \ No newline at end of file diff --git a/src/SDL_clipboard.bf b/src/SDL_clipboard.bf new file mode 100644 index 0000000..3fed35a --- /dev/null +++ b/src/SDL_clipboard.bf @@ -0,0 +1,342 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* 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 + */ +[LinkName("SDL_SetClipboardText")] public static extern bool SetClipboardText(c_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 + */ +[LinkName("SDL_GetClipboardText")] public static extern c_char* GetClipboardText(); + +/** + * 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 + */ +[LinkName("SDL_HasClipboardText")] public static extern bool HasClipboardText(); + +/** + * 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 + */ +[LinkName("SDL_SetPrimarySelectionText")] public static extern bool SetPrimarySelectionText(c_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 + */ +[LinkName("SDL_GetPrimarySelectionText")] public static extern c_char* GetPrimarySelectionText(); + +/** + * 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 + */ +[LinkName("SDL_HasPrimarySelectionText")] public static extern bool HasPrimarySelectionText(); + +/** + * 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 + */ +public function void* ClipboardDataCallback(void* userdata, c_char* mime_type, c_size* 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 + */ +public function void 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 + */ +[LinkName("SDL_SetClipboardData")] public static extern bool SetClipboardData(ClipboardDataCallback callback, ClipboardCleanupCallback cleanup, void* userdata, c_char** mime_types, c_size 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 + */ +[LinkName("SDL_ClearClipboardData")] public static extern bool ClearClipboardData(); + +/** + * 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 + */ +[LinkName("SDL_GetClipboardData")] public static extern void* GetClipboardData(c_char* mime_type, out c_size 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 + */ +[LinkName("SDL_HasClipboardData")] public static extern bool HasClipboardData(c_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 + */ +[LinkName("SDL_GetClipboardMimeTypes")] public static extern c_char** GetClipboardMimeTypes(c_size* num_mime_types); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_clipboard_h_ */ \ No newline at end of file diff --git a/src/SDL_close_code.bf b/src/SDL_close_code.bf new file mode 100644 index 0000000..de91ce6 --- /dev/null +++ b/src/SDL_close_code.bf @@ -0,0 +1,49 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +/* + 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. +*/ + +/* + * 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. + * + * SDL's headers use this; applications generally should not include this + * header directly. + */ + + + + + + +/* Reset structure packing at previous byte alignment */ + + + + + +/* Compiler needs structure packing set */ \ No newline at end of file diff --git a/src/SDL_cpuinfo.bf b/src/SDL_cpuinfo.bf new file mode 100644 index 0000000..c46e673 --- /dev/null +++ b/src/SDL_cpuinfo.bf @@ -0,0 +1,385 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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). + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public const let 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. + */ +[LinkName("SDL_GetNumLogicalCPUCores")] public static extern c_int GetNumLogicalCPUCores(); + +/** + * 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. + */ +[LinkName("SDL_GetCPUCacheLineSize")] public static extern c_int GetCPUCacheLineSize(); + +/** + * 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. + */ +[LinkName("SDL_HasAltiVec")] public static extern bool HasAltiVec(); + +/** + * 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. + */ +[LinkName("SDL_HasMMX")] public static extern bool HasMMX(); + +/** + * 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 + */ +[LinkName("SDL_HasSSE")] public static extern bool HasSSE(); + +/** + * 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 + */ +[LinkName("SDL_HasSSE2")] public static extern bool HasSSE2(); + +/** + * 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 + */ +[LinkName("SDL_HasSSE3")] public static extern bool HasSSE3(); + +/** + * 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 + */ +[LinkName("SDL_HasSSE41")] public static extern bool HasSSE41(); + +/** + * 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 + */ +[LinkName("SDL_HasSSE42")] public static extern bool HasSSE42(); + +/** + * 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 + */ +[LinkName("SDL_HasAVX")] public static extern bool HasAVX(); + +/** + * 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 + */ +[LinkName("SDL_HasAVX2")] public static extern bool HasAVX2(); + +/** + * 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 + */ +[LinkName("SDL_HasAVX512F")] public static extern bool HasAVX512F(); + +/** + * 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 + */ +[LinkName("SDL_HasARMSIMD")] public static extern bool HasARMSIMD(); + +/** + * 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. + */ +[LinkName("SDL_HasNEON")] public static extern bool HasNEON(); + +/** + * 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. + */ +[LinkName("SDL_HasLSX")] public static extern bool HasLSX(); + +/** + * 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. + */ +[LinkName("SDL_HasLASX")] public static extern bool HasLASX(); + +/** + * 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. + */ +[LinkName("SDL_GetSystemRAM")] public static extern c_int GetSystemRAM(); + +/** + * 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 + */ +[LinkName("SDL_GetSIMDAlignment")] public static extern c_size GetSIMDAlignment(); + +/** + * 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. + */ +[LinkName("SDL_GetSystemPageSize")] public static extern c_int GetSystemPageSize(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_cpuinfo_h_ */ \ No newline at end of file diff --git a/src/SDL_dialog.bf b/src/SDL_dialog.bf new file mode 100644 index 0000000..36c4cac --- /dev/null +++ b/src/SDL_dialog.bf @@ -0,0 +1,356 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[CRepr] public struct DialogFileFilter +{ + public c_char* name; + public c_char* pattern; +} + +/** + * 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 + */ +public function void DialogFileCallback(void* userdata, c_char** filelist, c_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 + */ +[LinkName("SDL_ShowOpenFileDialog")] public static extern void ShowOpenFileDialog(DialogFileCallback callback, void* userdata, Window* window, DialogFileFilter* filters, c_int nfilters, c_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 + */ +[LinkName("SDL_ShowSaveFileDialog")] public static extern void ShowSaveFileDialog(DialogFileCallback callback, void* userdata, Window* window, DialogFileFilter* filters, c_int nfilters, c_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 + */ +[LinkName("SDL_ShowOpenFolderDialog")] public static extern void ShowOpenFolderDialog(DialogFileCallback callback, void* userdata, Window* window, c_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 + */ +[AllowDuplicates] public enum FileDialogType : c_int +{ + Openfile, + Savefile, + Openfolder, +} + +/** + * 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 + */ +[LinkName("SDL_ShowFileDialogWithProperties")] public static extern void ShowFileDialogWithProperties(FileDialogType type, DialogFileCallback callback, void* userdata, PropertiesID props); + +public const let PROP_FILE_DIALOG_FILTERS_POINTER = "SDL.filedialog.filters"; +public const let PROP_FILE_DIALOG_NFILTERS_NUMBER = "SDL.filedialog.nfilters"; +public const let PROP_FILE_DIALOG_WINDOW_POINTER = "SDL.filedialog.window"; +public const let PROP_FILE_DIALOG_LOCATION_STRING = "SDL.filedialog.location"; +public const let PROP_FILE_DIALOG_MANY_BOOLEAN = "SDL.filedialog.many"; +public const let PROP_FILE_DIALOG_TITLE_STRING = "SDL.filedialog.title"; +public const let PROP_FILE_DIALOG_ACCEPT_STRING = "SDL.filedialog.accept"; +public const let PROP_FILE_DIALOG_CANCEL_STRING = "SDL.filedialog.cancel"; +} + + + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_dialog_h_ */ \ No newline at end of file diff --git a/src/SDL_dlopennote.bf b/src/SDL_dlopennote.bf new file mode 100644 index 0000000..f22ea48 --- /dev/null +++ b/src/SDL_dlopennote.bf @@ -0,0 +1,247 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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() + * ``` + */ + + + + +/** + * 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 + */ +public const let 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 + */ +public const let 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 + */ +public const let ELF_NOTE_DLOPEN_PRIORITY_REQUIRED = "required"; + + + +/* The dlopen note functionality isn't used on this platform */ + + + + +/* gcc < 3.1 too old */ + + + +/* SDL_PLATFORM_UNIX || SDL_PLATFORM_ANDROID */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* Create "unique" variable name using __LINE__, + * so creating multiple elf notes on the same line is not supported + */ + + + + +/** + * 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 + */ + + + + + + + + + + + + + + +/* Variadic macros are not supported */ + + + + +} + + + + + +/* SDL_dlopennote_h */ \ No newline at end of file diff --git a/src/SDL_endian.bf b/src/SDL_endian.bf new file mode 100644 index 0000000..91e67b7 --- /dev/null +++ b/src/SDL_endian.bf @@ -0,0 +1,653 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +/* + 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. + */ + + + + + + + +/* 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. */ + + + + + + + /* _MM_HINT_T0 */ + +/* __PRFCHWINTRIN_H */ +/* __clang__ */ + + + + +/** + * \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 + */ + + +/** + * 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 + */ + + +/* @} */ + + + + +/** + * 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 + */ + + + + + + + + + + + + + + + + + + + +/* predefs from newer gcc and clang versions: */ + + + + + + + +/**/ + + + + + + + + + + +/* SDL_PLATFORM_LINUX */ +/* !SDL_BYTEORDER */ + + + + +/** + * 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 + */ + +/* predefs from newer gcc versions: */ + + + + + + + +/**/ + +/* For Maverick, float words are always little-endian. */ + + +/* For FPA, float words are always big-endian. */ + + +/* By default, assume that floats words follow the memory system mode. */ + +/* __FLOAT_WORD_ORDER__ */ +/* !SDL_FLOATWORDORDER */ + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* various modern compilers may have builtin swap */ + + + + + + + + + /* this one is broken */ + + + + + + + + +/* Byte swap 16-bit integer. */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* Byte swap 32-bit integer. */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* Byte swap 64-bit integer. */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + /* Separate into high and low 32-bit values and swap them */ + + + + + + + + + + + +/** + * 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. + */ + + + + + + + + + + + +/* remove extra macros */ + + + + + + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + + + + + + + + + + + + + + + + + + + + + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_endian_h_ */ \ No newline at end of file diff --git a/src/SDL_error.bf b/src/SDL_error.bf new file mode 100644 index 0000000..f6c4789 --- /dev/null +++ b/src/SDL_error.bf @@ -0,0 +1,239 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* 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 + */ +[LinkName("SDL_SetError")] public static extern bool SetError(c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_SetErrorV")] public static extern bool SetErrorV(c_char* fmt, VarArgs ap); + +/** + * 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. + */ +[LinkName("SDL_OutOfMemory")] public static extern bool OutOfMemory(); + +/** + * 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 + */ +[LinkName("SDL_GetError")] public static extern c_char* GetError(); + +/** + * 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 + */ +[LinkName("SDL_ClearError")] public static extern bool ClearError(); + +/** + * \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. + */ + + +/** + * 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. + */ + +} + + + +/* @} */ /* Internal error functions */ + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_error_h_ */ \ No newline at end of file diff --git a/src/SDL_events.bf b/src/SDL_events.bf new file mode 100644 index 0000000..54da7eb --- /dev/null +++ b/src/SDL_events.bf @@ -0,0 +1,1656 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* General keyboard/mouse/pen state definitions */ + +/** + * The types of events that can be delivered. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum EventType : c_int +{ + First = 0, /**< Unused (do not remove) */ + + /* Application events */ + 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 */ + erminating, /**< 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() + */ + LowMemory, /**< 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() + */ + WillEnterBackground, /**< 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() + */ + DidEnterBackground, /**< 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() + */ + WillEnterForeground, /**< 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() + */ + DidEnterForeground, /**< 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() + */ + + LocaleChanged, /**< The user's locale preferences have changed. */ + + SystemThemeChanged, /**< The system theme changed */ + + /* Display events */ + /* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */ + DisplayOrientation = 0x151, /**< Display orientation has changed to data1 */ + DisplayAdded, /**< Display has been added to the system */ + DisplayRemoved, /**< Display has been removed from the system */ + DisplayMoved, /**< Display has changed position */ + DisplayDesktopModeChanged, /**< Display has changed desktop mode */ + DisplayCurrentModeChanged, /**< Display has changed current mode */ + DisplayContentScaleChanged, /**< Display has changed content scale */ + DisplayUsableBoundsChanged, /**< Display has changed usable bounds */ + DisplayFirst = DisplayOrientation, + DisplayLast = DisplayUsableBoundsChanged, + + /* Window events */ + /* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */ + /* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */ + WindowShown = 0x202, /**< Window has been shown */ + WindowHidden, /**< Window has been hidden */ + WindowExposed, /**< 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. */ + WindowMoved, /**< Window has been moved to data1, data2 */ + WindowResized, /**< Window has been resized to data1xdata2 */ + WindowPixelSizeChanged,/**< The pixel size of the window has changed to data1xdata2 */ + WindowMetalViewResized,/**< The pixel size of a Metal view associated with the window has changed */ + WindowMinimized, /**< Window has been minimized */ + WindowMaximized, /**< Window has been maximized */ + WindowRestored, /**< Window has been restored to normal size and position */ + WindowMouseEnter, /**< Window has gained mouse focus */ + WindowMouseLeave, /**< Window has lost mouse focus */ + WindowFocusGained, /**< Window has gained keyboard focus */ + WindowFocusLost, /**< Window has lost keyboard focus */ + WindowCloseRequested, /**< The window manager requests that the window be closed */ + WindowHitTest, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL */ + WindowIccprofChanged, /**< The ICC profile of the window's display has changed */ + WindowDisplayChanged, /**< Window has been moved to display data1 */ + WindowDisplayScaleChanged, /**< Window display scale has been changed */ + WindowSafeAreaChanged, /**< The window safe area has been changed */ + WindowOccluded, /**< The window has been occluded */ + WindowEnterFullscreen, /**< The window has entered fullscreen mode */ + WindowLeaveFullscreen, /**< The window has left fullscreen mode */ + WindowDestroyed, /**< 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 */ + WindowHdrStateChanged, /**< Window HDR properties have changed */ + WindowFirst = WindowShown, + WindowLast = WindowHdrStateChanged, + + /* Keyboard events */ + KeyDown = 0x300, /**< Key pressed */ + KeyUp, /**< Key released */ + extEditing, /**< Keyboard text editing (composition) */ + extInput, /**< Keyboard text input */ + KeymapChanged, /**< Keymap changed due to a system event such as an + input language or keyboard layout change. */ + KeyboardAdded, /**< A new keyboard has been inserted into the system */ + KeyboardRemoved, /**< A keyboard has been removed */ + extEditingCandidates, /**< Keyboard text editing candidates */ + ScreenKeyboardShown, /**< The on-screen keyboard has been shown */ + ScreenKeyboardHidden, /**< The on-screen keyboard has been hidden */ + + /* Mouse events */ + MouseMotion = 0x400, /**< Mouse moved */ + MouseButtonDown, /**< Mouse button pressed */ + MouseButtonUp, /**< Mouse button released */ + MouseWheel, /**< Mouse wheel motion */ + MouseAdded, /**< A new mouse has been inserted into the system */ + MouseRemoved, /**< A mouse has been removed */ + + /* Joystick events */ + JoystickAxisMotion = 0x600, /**< Joystick axis motion */ + JoystickBallMotion, /**< Joystick trackball motion */ + JoystickHatMotion, /**< Joystick hat position change */ + JoystickButtonDown, /**< Joystick button pressed */ + JoystickButtonUp, /**< Joystick button released */ + JoystickAdded, /**< A new joystick has been inserted into the system */ + JoystickRemoved, /**< An opened joystick has been removed */ + JoystickBatteryUpdated, /**< Joystick battery level change */ + JoystickUpdateComplete, /**< Joystick update is complete */ + + /* Gamepad events */ + GamepadAxisMotion = 0x650, /**< Gamepad axis motion */ + GamepadButtonDown, /**< Gamepad button pressed */ + GamepadButtonUp, /**< Gamepad button released */ + GamepadAdded, /**< A new gamepad has been inserted into the system */ + GamepadRemoved, /**< A gamepad has been removed */ + GamepadRemapped, /**< The gamepad mapping was updated */ + GamepadTouchpadDown, /**< Gamepad touchpad was touched */ + GamepadTouchpadMotion, /**< Gamepad touchpad finger was moved */ + GamepadTouchpadUp, /**< Gamepad touchpad finger was lifted */ + GamepadSensorUpdate, /**< Gamepad sensor was updated */ + GamepadUpdateComplete, /**< Gamepad update is complete */ + GamepadSteamHandleUpdated, /**< Gamepad Steam handle has changed */ + + /* Touch events */ + FingerDown = 0x700, + FingerUp, + FingerMotion, + FingerCanceled, + + /* Pinch events */ + PinchBegin = 0x710, /**< Pinch gesture started */ + PinchUpdate, /**< Pinch gesture updated */ + PinchEnd, /**< Pinch gesture ended */ + + /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ + + /* Clipboard events */ + ClipboardUpdate = 0x900, /**< The clipboard changed */ + + /* Drag and drop events */ + DropFile = 0x1000, /**< The system requests a file open */ + DropText, /**< text/plain drag-and-drop event */ + DropBegin, /**< A new set of drops is beginning (NULL filename) */ + DropComplete, /**< Current set of drops is now complete (NULL filename) */ + DropPosition, /**< Position while moving over the window */ + + /* Audio hotplug events */ + AudioDeviceAdded = 0x1100, /**< A new audio device is available */ + AudioDeviceRemoved, /**< An audio device has been removed. */ + AudioDeviceFormatChanged, /**< An audio device's format has been changed by the system. */ + + /* Sensor events */ + SensorUpdate = 0x1200, /**< A sensor was updated */ + + /* Pressure-sensitive pen events */ + PenProximityIn = 0x1300, /**< Pressure-sensitive pen has become available */ + PenProximityOut, /**< Pressure-sensitive pen has become unavailable */ + PenDown, /**< Pressure-sensitive pen touched drawing surface */ + PenUp, /**< Pressure-sensitive pen stopped touching drawing surface */ + PenButtonDown, /**< Pressure-sensitive pen button pressed */ + PenButtonUp, /**< Pressure-sensitive pen button released */ + PenMotion, /**< Pressure-sensitive pen is moving on the tablet */ + PenAxis, /**< Pressure-sensitive pen angle/pressure/etc changed */ + + /* Camera hotplug events */ + CameraDeviceAdded = 0x1400, /**< A new camera device is available */ + CameraDeviceRemoved, /**< A camera device has been removed. */ + CameraDeviceApproved, /**< A camera device has been approved for use by the user. */ + CameraDeviceDenied, /**< A camera device has been denied for use by the user. */ + + /* Render events */ + RenderTargetsReset = 0x2000, /**< The render targets have been reset and their contents need to be updated */ + RenderDeviceReset, /**< The device has been reset and all textures need to be recreated */ + RenderDeviceLost, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + Private0 = 0x4000, + Private1, + Private2, + Private3, + + /* Internal events */ + PollSentinel = 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() + */ + User = 0x8000, + + /** + * This last event is only for bounding internal arrays + */ + Last = 0xFFFF, + + /* This just makes sure the enum is the size of Uint32 */ + EnumPadding = 0x7FFFFFFF, + +} + +/** + * Fields shared by every event + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct CommonEvent +{ + public Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ +} + +/** + * Display state change event data (event.display.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct DisplayEvent +{ + public EventType type; /**< SDL_EVENT_DISPLAY_* */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public DisplayID displayID;/**< The associated display */ + public Sint32 data1; /**< event dependent data */ + public Sint32 data2; /**< event dependent data */ +} + +/** + * Window state change event data (event.window.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct WindowEvent +{ + public EventType type; /**< SDL_EVENT_WINDOW_* */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The associated window */ + public Sint32 data1; /**< event dependent data */ + public Sint32 data2; /**< event dependent data */ +} + +/** + * Keyboard device event structure (event.kdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct KeyboardDeviceEvent +{ + public EventType type; /**< SDL_EVENT_KEYBOARD_ADDED or SDL_EVENT_KEYBOARD_REMOVED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public KeyboardID which; /**< The keyboard instance id */ +} + +/** + * 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 + */ +[CRepr] public struct KeyboardEvent +{ + public EventType type; /**< SDL_EVENT_KEY_DOWN or SDL_EVENT_KEY_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with keyboard focus, if any */ + public KeyboardID which; /**< The keyboard instance id, or 0 if unknown or virtual */ + public Scancode scancode; /**< SDL physical key code */ + public Keycode key; /**< SDL virtual key code */ + public Keymod mod; /**< current key modifiers */ + public Uint16 raw; /**< The platform dependent scancode for this event */ + public bool down; /**< true if the key is pressed */ + public bool @repeat; /**< true if this is a key repeat */ +} + +/** + * 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. + */ +[CRepr] public struct TextEditingEvent +{ + public EventType type; /**< SDL_EVENT_TEXT_EDITING */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with keyboard focus, if any */ + public c_char* text; /**< The editing text */ + public Sint32 start; /**< The start cursor of selected editing text, or -1 if not set */ + public Sint32 length; /**< The length of selected editing text, or -1 if not set */ +} + +/** + * Keyboard IME candidates event structure (event.edit_candidates.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct TextEditingCandidatesEvent +{ + public EventType type; /**< SDL_EVENT_TEXT_EDITING_CANDIDATES */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with keyboard focus, if any */ + public c_char** candidates; /**< The list of candidates, or NULL if there are no candidates available */ + public Sint32 num_candidates; /**< The number of strings in `candidates` */ + public Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ + public bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * 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 + */ +[CRepr] public struct TextInputEvent +{ + public EventType type; /**< SDL_EVENT_TEXT_INPUT */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with keyboard focus, if any */ + public c_char* text; /**< The input text, UTF-8 encoded */ +} + +/** + * Mouse device event structure (event.mdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MouseDeviceEvent +{ + public EventType type; /**< SDL_EVENT_MOUSE_ADDED or SDL_EVENT_MOUSE_REMOVED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public MouseID which; /**< The mouse instance id */ +} + +/** + * Mouse motion event structure (event.motion.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MouseMotionEvent +{ + public EventType type; /**< SDL_EVENT_MOUSE_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with mouse focus, if any */ + public MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ + public MouseButtonFlags state; /**< The current button state */ + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ + public float xrel; /**< The relative motion in the X direction */ + public float yrel; /**< The relative motion in the Y direction */ +} + +/** + * Mouse button event structure (event.button.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MouseButtonEvent +{ + public EventType type; /**< SDL_EVENT_MOUSE_BUTTON_DOWN or SDL_EVENT_MOUSE_BUTTON_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with mouse focus, if any */ + public MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ + public Uint8 button; /**< The mouse button index */ + public bool down; /**< true if the button is pressed */ + public Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ + public Uint8 padding; + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ +} + +/** + * Mouse wheel event structure (event.wheel.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MouseWheelEvent +{ + public EventType type; /**< SDL_EVENT_MOUSE_WHEEL */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with mouse focus, if any */ + public MouseID which; /**< The mouse instance id in relative mode or 0 */ + public float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ + public float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ + public 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 */ + public float mouse_x; /**< X coordinate, relative to window */ + public float mouse_y; /**< Y coordinate, relative to window */ + public Sint32 integer_x; /**< The amount scrolled horizontally, accumulated to whole scroll "ticks" (added in 3.2.12) */ + public Sint32 integer_y; /**< The amount scrolled vertically, accumulated to whole scroll "ticks" (added in 3.2.12) */ +} + +/** + * Joystick axis motion event structure (event.jaxis.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct JoyAxisEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_AXIS_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 axis; /**< The joystick axis index */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; + public Sint16 value; /**< The axis value (range: -32768 to 32767) */ + public Uint16 padding4; +} + +/** + * Joystick trackball motion event structure (event.jball.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct JoyBallEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_BALL_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 ball; /**< The joystick trackball index */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; + public Sint16 xrel; /**< The relative motion in the X direction */ + public Sint16 yrel; /**< The relative motion in the Y direction */ +} + +/** + * Joystick hat position change event structure (event.jhat.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct JoyHatEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_HAT_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 hat; /**< The joystick hat index */ + public 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. + */ + public Uint8 padding1; + public Uint8 padding2; +} + +/** + * Joystick button event structure (event.jbutton.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct JoyButtonEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_BUTTON_DOWN or SDL_EVENT_JOYSTICK_BUTTON_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 button; /**< The joystick button index */ + public bool down; /**< true if the button is pressed */ + public Uint8 padding1; + public Uint8 padding2; +} + +/** + * 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 + */ +[CRepr] public struct JoyDeviceEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_ADDED or SDL_EVENT_JOYSTICK_REMOVED or SDL_EVENT_JOYSTICK_UPDATE_COMPLETE */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ +} + +/** + * Joystick battery level change event structure (event.jbattery.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct JoyBatteryEvent +{ + public EventType type; /**< SDL_EVENT_JOYSTICK_BATTERY_UPDATED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public PowerState state; /**< The joystick battery state */ + public c_int percent; /**< The joystick battery percent charge remaining */ +} + +/** + * Gamepad axis motion event structure (event.gaxis.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct GamepadAxisEvent +{ + public EventType type; /**< SDL_EVENT_GAMEPAD_AXIS_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 axis; /**< The gamepad axis (SDL_GamepadAxis) */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; + public Sint16 value; /**< The axis value (range: -32768 to 32767) */ + public Uint16 padding4; +} + + +/** + * Gamepad button event structure (event.gbutton.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct GamepadButtonEvent +{ + public EventType type; /**< SDL_EVENT_GAMEPAD_BUTTON_DOWN or SDL_EVENT_GAMEPAD_BUTTON_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ + public bool down; /**< true if the button is pressed */ + public Uint8 padding1; + public Uint8 padding2; +} + + +/** + * 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 + */ +[CRepr] public struct GamepadDeviceEvent +{ + public 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 */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ +} + +/** + * Gamepad touchpad event structure (event.gtouchpad.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct GamepadTouchpadEvent +{ + public EventType type; /**< SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN or SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION or SDL_EVENT_GAMEPAD_TOUCHPAD_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Sint32 touchpad; /**< The index of the touchpad */ + public Sint32 finger; /**< The index of the finger on the touchpad */ + public float x; /**< Normalized in the range 0...1 with 0 being on the left */ + public float y; /**< Normalized in the range 0...1 with 0 being at the top */ + public float pressure; /**< Normalized in the range 0...1 */ +} + +/** + * Gamepad sensor event structure (event.gsensor.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct GamepadSensorEvent +{ + public EventType type; /**< SDL_EVENT_GAMEPAD_SENSOR_UPDATE */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public JoystickID which; /**< The joystick instance id */ + public Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */ + public float[3] data; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ + public Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */ +} + +/** + * 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. + */ +[CRepr] public struct AudioDeviceEvent +{ + public EventType type; /**< SDL_EVENT_AUDIO_DEVICE_ADDED, or SDL_EVENT_AUDIO_DEVICE_REMOVED, or SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ + public bool recording; /**< false if a playback device, true if a recording device. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * Camera device event structure (event.cdevice.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct CameraDeviceEvent +{ + public EventType type; /**< SDL_EVENT_CAMERA_DEVICE_ADDED, SDL_EVENT_CAMERA_DEVICE_REMOVED, SDL_EVENT_CAMERA_DEVICE_APPROVED, SDL_EVENT_CAMERA_DEVICE_DENIED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ +} + + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct RenderEvent +{ + public EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window containing the renderer in question. */ +} + + +/** + * 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. + */ +[CRepr] public struct TouchFingerEvent +{ + public EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public TouchID touchID; /**< The touch device id */ + public FingerID fingerID; + public float x; /**< Normalized in the range 0...1 */ + public float y; /**< Normalized in the range 0...1 */ + public float dx; /**< Normalized in the range -1...1 */ + public float dy; /**< Normalized in the range -1...1 */ + public float pressure; /**< Normalized in the range 0...1 */ + public WindowID windowID; /**< The window underneath the finger, if any */ +} + +/** + * Pinch event structure (event.pinch.*) + */ +[CRepr] public struct PinchFingerEvent +{ + public EventType type; /**< ::SDL_EVENT_PINCH_BEGIN or ::SDL_EVENT_PINCH_UPDATE or ::SDL_EVENT_PINCH_END */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public float scale; /**< The scale change since the last SDL_EVENT_PINCH_UPDATE. Scale < 1 is "zoom out". Scale > 1 is "zoom in". */ + public WindowID windowID; /**< The window underneath the finger, if any */ +} + +/** + * 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. + */ +[CRepr] public struct PenProximityEvent +{ + public EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with pen focus, if any */ + public PenID which; /**< The pen instance id */ +} + +/** + * 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. + */ +[CRepr] public struct PenMotionEvent +{ + public EventType type; /**< SDL_EVENT_PEN_MOTION */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with pen focus, if any */ + public PenID which; /**< The pen instance id */ + public PenInputFlags pen_state; /**< Complete pen input state at time of event */ + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ +} + +/** + * 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. + */ +[CRepr] public struct PenTouchEvent +{ + public EventType type; /**< SDL_EVENT_PEN_DOWN or SDL_EVENT_PEN_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with pen focus, if any */ + public PenID which; /**< The pen instance id */ + public PenInputFlags pen_state; /**< Complete pen input state at time of event */ + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ + public bool eraser; /**< true if eraser end is used (not all pens support this). */ + public bool down; /**< true if the pen is touching or false if the pen is lifted off */ +} + +/** + * 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. + */ +[CRepr] public struct PenButtonEvent +{ + public EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with mouse focus, if any */ + public PenID which; /**< The pen instance id */ + public PenInputFlags pen_state; /**< Complete pen input state at time of event */ + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ + public Uint8 button; /**< The pen button index (first button is 1). */ + public bool down; /**< true if the button is pressed */ +} + +/** + * 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. + */ +[CRepr] public struct PenAxisEvent +{ + public EventType type; /**< SDL_EVENT_PEN_AXIS */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window with pen focus, if any */ + public PenID which; /**< The pen instance id */ + public PenInputFlags pen_state; /**< Complete pen input state at time of event */ + public float x; /**< X coordinate, relative to window */ + public float y; /**< Y coordinate, relative to window */ + public PenAxis axis; /**< Axis that has changed */ + public float value; /**< New value of axis */ +} + +/** + * 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. + */ +[CRepr] public struct DropEvent +{ + public 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 */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The window that was dropped on, if any */ + public float x; /**< X coordinate, relative to window (not on begin) */ + public float y; /**< Y coordinate, relative to window (not on begin) */ + public c_char* source; /**< The source app that sent this drop event, or NULL if that isn't available */ + public c_char* data; /**< The text for SDL_EVENT_DROP_TEXT and the file name for SDL_EVENT_DROP_FILE, NULL for other events */ +} + +/** + * An event triggered when the clipboard contents have changed + * (event.clipboard.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct ClipboardEvent +{ + public EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public bool owner; /**< are we owning the clipboard (internal update) */ + public Sint32 num_mime_types; /**< number of mime types */ + public c_char** mime_types; /**< current mime types */ +} + +/** + * Sensor event structure (event.sensor.*) + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct SensorEvent +{ + public EventType type; /**< SDL_EVENT_SENSOR_UPDATE */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public SensorID which; /**< The instance ID of the sensor */ + public float[6] data; /**< Up to 6 values from the sensor - additional values can be queried using SDL_GetSensorData() */ + public Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */ +} + +/** + * The "quit requested" event + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct QuitEvent +{ + public EventType type; /**< SDL_EVENT_QUIT */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ +} + +/** + * 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. + */ +[CRepr] public struct UserEvent +{ + public Uint32 type; /**< SDL_EVENT_USER through SDL_EVENT_LAST, Uint32 because these are not in the SDL_EventType enumeration */ + public Uint32 reserved; + public Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + public WindowID windowID; /**< The associated window if any */ + public Sint32 code; /**< User defined event code */ + public void* data1; /**< User defined data pointer */ + public void* data2; /**< User defined data pointer */ +} + + +/** + * 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. + */ +[CRepr, Union] public struct Event +{ + public Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */ + public CommonEvent common; /**< Common event data */ + public DisplayEvent display; /**< Display event data */ + public WindowEvent window; /**< Window event data */ + public KeyboardDeviceEvent kdevice; /**< Keyboard device change event data */ + public KeyboardEvent key; /**< Keyboard event data */ + public TextEditingEvent edit; /**< Text editing event data */ + public TextEditingCandidatesEvent edit_candidates; /**< Text editing candidates event data */ + public TextInputEvent text; /**< Text input event data */ + public MouseDeviceEvent mdevice; /**< Mouse device change event data */ + public MouseMotionEvent motion; /**< Mouse motion event data */ + public MouseButtonEvent button; /**< Mouse button event data */ + public MouseWheelEvent wheel; /**< Mouse wheel event data */ + public JoyDeviceEvent jdevice; /**< Joystick device change event data */ + public JoyAxisEvent jaxis; /**< Joystick axis event data */ + public JoyBallEvent jball; /**< Joystick ball event data */ + public JoyHatEvent jhat; /**< Joystick hat event data */ + public JoyButtonEvent jbutton; /**< Joystick button event data */ + public JoyBatteryEvent jbattery; /**< Joystick battery event data */ + public GamepadDeviceEvent gdevice; /**< Gamepad device event data */ + public GamepadAxisEvent gaxis; /**< Gamepad axis event data */ + public GamepadButtonEvent gbutton; /**< Gamepad button event data */ + public GamepadTouchpadEvent gtouchpad; /**< Gamepad touchpad event data */ + public GamepadSensorEvent gsensor; /**< Gamepad sensor event data */ + public AudioDeviceEvent adevice; /**< Audio device event data */ + public CameraDeviceEvent cdevice; /**< Camera device event data */ + public SensorEvent sensor; /**< Sensor event data */ + public QuitEvent quit; /**< Quit request event data */ + public UserEvent user; /**< Custom event data */ + public TouchFingerEvent tfinger; /**< Touch finger event data */ + public PinchFingerEvent pinch; /**< Pinch event data */ + public PenProximityEvent pproximity; /**< Pen proximity event data */ + public PenTouchEvent ptouch; /**< Pen tip touching event data */ + public PenMotionEvent pmotion; /**< Pen motion event data */ + public PenButtonEvent pbutton; /**< Pen button event data */ + public PenAxisEvent paxis; /**< Pen axis event data */ + public RenderEvent render; /**< Render event data */ + public DropEvent drop; /**< Drag and drop event data */ + public 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. + */ + public Uint8[128] padding; +} + +/* Make sure we haven't broken binary compatibility */ + + + +/* 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 + */ +[LinkName("SDL_PumpEvents")] public static extern void PumpEvents(); + +/* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum EventAction : c_int +{ + Addevent, /**< Add events to the back of the queue. */ + Peekevent, /**< Check but don't remove events from the queue front. */ + Getevent, /**< Retrieve/remove events from the front of the queue. */ +} + +/** + * 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 + */ +[LinkName("SDL_PeepEvents")] public static extern c_int PeepEvents(Event* events, c_int numevents, 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 + */ +[LinkName("SDL_HasEvent")] public static extern bool 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 + */ +[LinkName("SDL_HasEvents")] public static extern bool 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 + */ +[LinkName("SDL_FlushEvent")] public static extern void 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 + */ +[LinkName("SDL_FlushEvents")] public static extern void 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 + */ +[LinkName("SDL_PollEvent")] public static extern bool PollEvent(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 + */ +[LinkName("SDL_WaitEvent")] public static extern bool WaitEvent(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 + */ +[LinkName("SDL_WaitEventTimeout")] public static extern bool WaitEventTimeout(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 + */ +[LinkName("SDL_PushEvent")] public static extern bool PushEvent(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 + */ +public function bool EventFilter(void* userdata, 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 + */ +[LinkName("SDL_SetEventFilter")] public static extern void SetEventFilter(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 + */ +[LinkName("SDL_GetEventFilter")] public static extern bool GetEventFilter(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 + */ +[LinkName("SDL_AddEventWatch")] public static extern bool AddEventWatch(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 + */ +[LinkName("SDL_RemoveEventWatch")] public static extern void RemoveEventWatch(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 + */ +[LinkName("SDL_FilterEvents")] public static extern void FilterEvents(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 + */ +[LinkName("SDL_SetEventEnabled")] public static extern void 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 + */ +[LinkName("SDL_EventEnabled")] public static extern bool 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 + */ +[LinkName("SDL_RegisterEvents")] public static extern Uint32 RegisterEvents(c_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 + */ +[LinkName("SDL_GetWindowFromEvent")] public static extern Window* GetWindowFromEvent(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. + */ +[LinkName("SDL_GetEventDescription")] public static extern c_int GetEventDescription(Event* event, c_char* buf, c_int buflen); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_events_h_ */ \ No newline at end of file diff --git a/src/SDL_filesystem.bf b/src/SDL_filesystem.bf new file mode 100644 index 0000000..b5d630c --- /dev/null +++ b/src/SDL_filesystem.bf @@ -0,0 +1,563 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[LinkName("SDL_GetBasePath")] public static extern c_char* GetBasePath(); + +/** + * 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 + */ +[LinkName("SDL_GetPrefPath")] public static extern c_char* GetPrefPath(c_char* org, c_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 + */ +[AllowDuplicates] public enum Folder : c_int +{ + 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. */ + 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. */ + Documents, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + Downloads, /**< Standard folder for user files downloaded from the internet. */ + Music, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + Pictures, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + Publicshare, /**< Files that are meant to be shared with other users on the same computer. */ + Savedgames, /**< Save files for games. */ + Screenshots, /**< Application screenshots. */ + 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. */ + Videos, /**< Video files that can be played using a standard video player (mp4, webm...). */ + Count, /**< Total number of types in this enum, not a folder type by itself. */ +} + +/** + * 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. + */ +[LinkName("SDL_GetUserFolder")] public static extern c_char* GetUserFolder(Folder folder); + + +/* Abstract filesystem interface */ + +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ +[AllowDuplicates] public enum PathType : c_int +{ + None, /**< path does not exist */ + File, /**< a normal file */ + Directory, /**< a directory */ + Other, /**< something completely different like a device node (not a symlink, those are always followed) */ +} + +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ +[CRepr] public struct PathInfo +{ + public PathType type; /**< the path type */ + public Uint64 size; /**< the file size in bytes */ + public Time create_time; /**< the time when the path was created */ + public Time modify_time; /**< the last time the path was modified */ + public Time access_time; /**< the last time the path was read */ +} + +/** + * Flags for path matching. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GlobDirectory + * \sa SDL_GlobStorageDirectory + */ +public enum GlobFlags : Uint32 +{ + 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. + */ +} + +/** + * 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. + */ +[LinkName("SDL_CreateDirectory")] public static extern bool CreateDirectory(c_char* path); + +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +[AllowDuplicates] public enum EnumerationResult : c_int +{ + Continue, /**< Value that requests that enumeration continue. */ + Success, /**< Value that requests that enumeration stop, successfully. */ + Failure, /**< Value that requests that enumeration stop, as a failure. */ +} + +/** + * 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 + */ +public function EnumerationResult EnumerateDirectoryCallback(void* userdata, c_char* dirname, c_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. + */ +[LinkName("SDL_EnumerateDirectory")] public static extern bool EnumerateDirectory(c_char* path, 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. + */ +[LinkName("SDL_RemovePath")] public static extern bool RemovePath(c_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. + */ +[LinkName("SDL_RenamePath")] public static extern bool RenamePath(c_char* oldpath, c_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. + */ +[LinkName("SDL_CopyFile")] public static extern bool CopyFile(c_char* oldpath, c_char* newpath); + +/** + * Get information about a filesystem path. + * + * \param path the path to query. + * \param info a pointer filled in with information about the path, or NULL to + * check for the existence of a file. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetPathInfo")] public static extern bool GetPathInfo(c_char* path, out 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. + */ +[LinkName("SDL_GlobDirectory")] public static extern c_char** GlobDirectory(c_char* path, c_char* pattern, GlobFlags flags, c_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. + */ +[LinkName("SDL_GetCurrentDirectory")] public static extern c_char* GetCurrentDirectory(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_filesystem_h_ */ \ No newline at end of file diff --git a/src/SDL_gamepad.bf b/src/SDL_gamepad.bf new file mode 100644 index 0000000..59c7b06 --- /dev/null +++ b/src/SDL_gamepad.bf @@ -0,0 +1,1713 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * The structure used to identify an SDL gamepad + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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). + */ +[AllowDuplicates] public enum GamepadType : c_int +{ + Unknown = 0, + Standard, + Xbox360, + Xboxone, + Ps3, + Ps4, + Ps5, + NintendoSwitchPro, + NintendoSwitchJoyconLeft, + NintendoSwitchJoyconRight, + NintendoSwitchJoyconPair, + Gamecube, + Count, +} + +/** + * 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. + */ +[AllowDuplicates] public enum GamepadButton : c_int +{ + Invalid = -1, + South, /**< Bottom face button (e.g. Xbox A button) */ + East, /**< Right face button (e.g. Xbox B button) */ + West, /**< Left face button (e.g. Xbox X button) */ + North, /**< Top face button (e.g. Xbox Y button) */ + Back, + Guide, + Start, + LeftStick, + RightStick, + LeftShoulder, + RightShoulder, + DpadUp, + DpadDown, + DpadLeft, + DpadRight, + Misc1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + RightPaddle1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1, DualSense Edge RB button, Right Joy-Con SR button) */ + LeftPaddle1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3, DualSense Edge LB button, Left Joy-Con SL button) */ + RightPaddle2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2, DualSense Edge right Fn button, Right Joy-Con SL button) */ + LeftPaddle2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4, DualSense Edge left Fn button, Left Joy-Con SR button) */ + Touchpad, /**< PS4/PS5 touchpad button */ + Misc2, /**< Additional button */ + Misc3, /**< Additional button (e.g. Nintendo GameCube left trigger click) */ + Misc4, /**< Additional button (e.g. Nintendo GameCube right trigger click) */ + Misc5, /**< Additional button */ + Misc6, /**< Additional button */ + Count, +} + +/** + * 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. + */ +[AllowDuplicates] public enum GamepadButtonLabel : c_int +{ + Unknown, + A, + B, + X, + Y, + Cross, + Circle, + Square, + Triangle, +} + +/** + * 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. + */ +[AllowDuplicates] public enum GamepadAxis : c_int +{ + Invalid = -1, + Leftx, + Lefty, + Rightx, + Righty, + LeftTrigger, + RightTrigger, + Count, +} + +/** + * 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. + */ +[AllowDuplicates] public enum GamepadBindingType : c_int +{ + None = 0, + Button, + Axis, + Hat, +} + +/** + * 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 + */ +[CRepr] public struct GamepadBinding +{ + public GamepadBindingType input_type; + + + + + + + + + + + + + + + + + + public [CRepr, Union] public struct + { + public c_int button; + + + + + + + public [CRepr] public struct + { + public c_int axis; + public c_int axis_min; + public c_int axis_max; + } axis; + + + + + + + public [CRepr] public struct + { + public c_int hat; + public c_int hat_mask; + } hat; + } input; + + + + + public GamepadBindingType output_type; + + + + + + + + + + + + public [CRepr, Union] public struct + { + public GamepadButton button; + + + + + + + public [CRepr] public struct + { + public GamepadAxis axis; + public c_int axis_min; + public c_int axis_max; + } axis; + } output; + } + + + + + +/** + * 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 + */ +[LinkName("SDL_AddGamepadMapping")] public static extern c_int AddGamepadMapping(c_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 + */ +[LinkName("SDL_AddGamepadMappingsFromIO")] public static extern c_int AddGamepadMappingsFromIO(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 + */ +[LinkName("SDL_AddGamepadMappingsFromFile")] public static extern c_int AddGamepadMappingsFromFile(c_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. + */ +[LinkName("SDL_ReloadGamepadMappings")] public static extern bool ReloadGamepadMappings(); + +/** + * 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. + */ +[LinkName("SDL_GetGamepadMappings")] public static extern c_char** GetGamepadMappings(out c_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 + */ +[LinkName("SDL_GetGamepadMappingForGUID")] public static extern c_char* GetGamepadMappingForGUID(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 + */ +[LinkName("SDL_GetGamepadMapping")] public static extern c_char* GetGamepadMapping(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 + */ +[LinkName("SDL_SetGamepadMapping")] public static extern bool SetGamepadMapping(JoystickID instance_id, c_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 + */ +[LinkName("SDL_HasGamepad")] public static extern bool HasGamepad(); + +/** + * 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 + */ +[LinkName("SDL_GetGamepads")] public static extern JoystickID* GetGamepads(out c_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 + */ +[LinkName("SDL_IsGamepad")] public static extern bool IsGamepad(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 + */ +[LinkName("SDL_GetGamepadNameForID")] public static extern c_char* GetGamepadNameForID(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 + */ +[LinkName("SDL_GetGamepadPathForID")] public static extern c_char* GetGamepadPathForID(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 + */ +[LinkName("SDL_GetGamepadPlayerIndexForID")] public static extern c_int GetGamepadPlayerIndexForID(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 + */ +[LinkName("SDL_GetGamepadGUIDForID")] public static extern GUID GetGamepadGUIDForID(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 + */ +[LinkName("SDL_GetGamepadVendorForID")] public static extern Uint16 GetGamepadVendorForID(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 + */ +[LinkName("SDL_GetGamepadProductForID")] public static extern Uint16 GetGamepadProductForID(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 + */ +[LinkName("SDL_GetGamepadProductVersionForID")] public static extern Uint16 GetGamepadProductVersionForID(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 + */ +[LinkName("SDL_GetGamepadTypeForID")] public static extern GamepadType GetGamepadTypeForID(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 + */ +[LinkName("SDL_GetRealGamepadTypeForID")] public static extern GamepadType GetRealGamepadTypeForID(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 + */ +[LinkName("SDL_GetGamepadMappingForID")] public static extern c_char* GetGamepadMappingForID(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 + */ +[LinkName("SDL_OpenGamepad")] public static extern Gamepad* OpenGamepad(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. + */ +[LinkName("SDL_GetGamepadFromID")] public static extern Gamepad* GetGamepadFromID(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 + */ +[LinkName("SDL_GetGamepadFromPlayerIndex")] public static extern Gamepad* GetGamepadFromPlayerIndex(c_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. + */ +[LinkName("SDL_GetGamepadProperties")] public static extern PropertiesID GetGamepadProperties(Gamepad* gamepad); + +public const let PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN = PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN; +public const let PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN = PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN; +public const let PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN = PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN; +public const let PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN = PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN; +public const let PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN = 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. + */ +[LinkName("SDL_GetGamepadID")] public static extern JoystickID GetGamepadID(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 + */ +[LinkName("SDL_GetGamepadName")] public static extern c_char* GetGamepadName(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 + */ +[LinkName("SDL_GetGamepadPath")] public static extern c_char* GetGamepadPath(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 + */ +[LinkName("SDL_GetGamepadType")] public static extern GamepadType GetGamepadType(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 + */ +[LinkName("SDL_GetRealGamepadType")] public static extern GamepadType GetRealGamepadType(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 + */ +[LinkName("SDL_GetGamepadPlayerIndex")] public static extern c_int GetGamepadPlayerIndex(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 + */ +[LinkName("SDL_SetGamepadPlayerIndex")] public static extern bool SetGamepadPlayerIndex(Gamepad* gamepad, c_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 + */ +[LinkName("SDL_GetGamepadVendor")] public static extern Uint16 GetGamepadVendor(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 + */ +[LinkName("SDL_GetGamepadProduct")] public static extern Uint16 GetGamepadProduct(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 + */ +[LinkName("SDL_GetGamepadProductVersion")] public static extern Uint16 GetGamepadProductVersion(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. + */ +[LinkName("SDL_GetGamepadFirmwareVersion")] public static extern Uint16 GetGamepadFirmwareVersion(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. + */ +[LinkName("SDL_GetGamepadSerial")] public static extern c_char* GetGamepadSerial(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. + */ +[LinkName("SDL_GetGamepadSteamHandle")] public static extern Uint64 GetGamepadSteamHandle(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. + */ +[LinkName("SDL_GetGamepadConnectionState")] public static extern JoystickConnectionState GetGamepadConnectionState(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. + */ +[LinkName("SDL_GetGamepadPowerInfo")] public static extern PowerState GetGamepadPowerInfo(Gamepad* gamepad, out c_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. + */ +[LinkName("SDL_GamepadConnected")] public static extern bool GamepadConnected(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. + */ +[LinkName("SDL_GetGamepadJoystick")] public static extern Joystick* GetGamepadJoystick(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 + */ +[LinkName("SDL_SetGamepadEventsEnabled")] public static extern void 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 + */ +[LinkName("SDL_GamepadEventsEnabled")] public static extern bool GamepadEventsEnabled(); + +/** + * 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. + */ +[LinkName("SDL_GetGamepadBindings")] public static extern GamepadBinding** GetGamepadBindings(Gamepad* gamepad, out c_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. + */ +[LinkName("SDL_UpdateGamepads")] public static extern void UpdateGamepads(); + +/** + * 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 + */ +[LinkName("SDL_GetGamepadTypeFromString")] public static extern GamepadType GetGamepadTypeFromString(c_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 + */ +[LinkName("SDL_GetGamepadStringForType")] public static extern c_char* GetGamepadStringForType(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 + */ +[LinkName("SDL_GetGamepadAxisFromString")] public static extern GamepadAxis GetGamepadAxisFromString(c_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 + */ +[LinkName("SDL_GetGamepadStringForAxis")] public static extern c_char* GetGamepadStringForAxis(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 + */ +[LinkName("SDL_GamepadHasAxis")] public static extern bool GamepadHasAxis(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetGamepadAxis")] public static extern Sint16 GetGamepadAxis(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetGamepadButtonFromString")] public static extern GamepadButton GetGamepadButtonFromString(c_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 + */ +[LinkName("SDL_GetGamepadStringForButton")] public static extern c_char* GetGamepadStringForButton(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 + */ +[LinkName("SDL_GamepadHasButton")] public static extern bool GamepadHasButton(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetGamepadButton")] public static extern bool GetGamepadButton(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetGamepadButtonLabelForType")] public static extern GamepadButtonLabel GetGamepadButtonLabelForType(GamepadType type, 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 + */ +[LinkName("SDL_GetGamepadButtonLabel")] public static extern GamepadButtonLabel GetGamepadButtonLabel(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetNumGamepadTouchpads")] public static extern c_int GetNumGamepadTouchpads(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 + */ +[LinkName("SDL_GetNumGamepadTouchpadFingers")] public static extern c_int GetNumGamepadTouchpadFingers(Gamepad* gamepad, c_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 + */ +[LinkName("SDL_GetGamepadTouchpadFinger")] public static extern bool GetGamepadTouchpadFinger(Gamepad* gamepad, c_int touchpad, c_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 + */ +[LinkName("SDL_GamepadHasSensor")] public static extern bool GamepadHasSensor(Gamepad* gamepad, 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 + */ +[LinkName("SDL_SetGamepadSensorEnabled")] public static extern bool SetGamepadSensorEnabled(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GamepadSensorEnabled")] public static extern bool GamepadSensorEnabled(Gamepad* gamepad, 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. + */ +[LinkName("SDL_GetGamepadSensorDataRate")] public static extern float GetGamepadSensorDataRate(Gamepad* gamepad, 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. + */ +[LinkName("SDL_GetGamepadSensorData")] public static extern bool GetGamepadSensorData(Gamepad* gamepad, SensorType type, float* data, c_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. + */ +[LinkName("SDL_RumbleGamepad")] public static extern bool RumbleGamepad(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 + */ +[LinkName("SDL_RumbleGamepadTriggers")] public static extern bool RumbleGamepadTriggers(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. + */ +[LinkName("SDL_SetGamepadLED")] public static extern bool SetGamepadLED(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. + */ +[LinkName("SDL_SendGamepadEffect")] public static extern bool SendGamepadEffect(Gamepad* gamepad, void* data, c_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 + */ +[LinkName("SDL_CloseGamepad")] public static extern void CloseGamepad(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 + */ +[LinkName("SDL_GetGamepadAppleSFSymbolsNameForButton")] public static extern c_char* GetGamepadAppleSFSymbolsNameForButton(Gamepad* gamepad, 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 + */ +[LinkName("SDL_GetGamepadAppleSFSymbolsNameForAxis")] public static extern c_char* GetGamepadAppleSFSymbolsNameForAxis(Gamepad* gamepad, GamepadAxis axis); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_gamepad_h_ */ \ No newline at end of file diff --git a/src/SDL_gpu.bf b/src/SDL_gpu.bf new file mode 100644 index 0000000..c570adb --- /dev/null +++ b/src/SDL_gpu.bf @@ -0,0 +1,4374 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + + + +/* __cplusplus */ + +/* Type Declarations */ + +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct 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 + */ +[AllowDuplicates] public enum GPUPrimitiveType : c_int +{ + Trianglelist, /**< A series of separate triangles. */ + Trianglestrip, /**< A series of connected triangles. */ + Linelist, /**< A series of separate lines. */ + Linestrip, /**< A series of connected lines. */ + Pointlist, /**< A series of separate points. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPULoadOp : c_int +{ + Load, /**< The previous contents of the texture will be preserved. */ + Clear, /**< The contents of the texture will be cleared to a color. */ + DontCare, /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUStoreOp : c_int +{ + Store, /**< The contents generated during the render pass will be written to memory. */ + DontCare, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + 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. */ + ResolveAndStore, /**< 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. */ +} + +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +[AllowDuplicates] public enum GPUIndexElementSize : c_int +{ + _16bit, /**< The index elements are 16-bit. */ + _32bit, /**< The index elements are 32-bit. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUTextureFormat : c_int +{ + INVALID, + + /* Unsigned Normalized Float Color Formats */ + A8_UNORM, + R8_UNORM, + R8G8_UNORM, + R8G8B8A8_UNORM, + R16_UNORM, + R16G16_UNORM, + R16G16B16A16_UNORM, + R10G10B10A2_UNORM, + B5G6R5_UNORM, + B5G5R5A1_UNORM, + B4G4R4A4_UNORM, + B8G8R8A8_UNORM, + /* Compressed Unsigned Normalized Float Color Formats */ + BC1_RGBA_UNORM, + BC2_RGBA_UNORM, + BC3_RGBA_UNORM, + BC4_R_UNORM, + BC5_RG_UNORM, + BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + BC6H_RGB_UFLOAT, + /* Signed Normalized Float Color Formats */ + R8_SNORM, + R8G8_SNORM, + R8G8B8A8_SNORM, + R16_SNORM, + R16G16_SNORM, + R16G16B16A16_SNORM, + /* Signed Float Color Formats */ + R16_FLOAT, + R16G16_FLOAT, + R16G16B16A16_FLOAT, + R32_FLOAT, + R32G32_FLOAT, + R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + R11G11B10_UFLOAT, + /* Unsigned Integer Color Formats */ + R8_UINT, + R8G8_UINT, + R8G8B8A8_UINT, + R16_UINT, + R16G16_UINT, + R16G16B16A16_UINT, + R32_UINT, + R32G32_UINT, + R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + R8_INT, + R8G8_INT, + R8G8B8A8_INT, + R16_INT, + R16G16_INT, + R16G16B16A16_INT, + R32_INT, + R32G32_INT, + R32G32B32A32_INT, + /* SRGB Unsigned Normalized Color Formats */ + R8G8B8A8_UNORM_SRGB, + B8G8R8A8_UNORM_SRGB, + /* Compressed SRGB Unsigned Normalized Color Formats */ + BC1_RGBA_UNORM_SRGB, + BC2_RGBA_UNORM_SRGB, + BC3_RGBA_UNORM_SRGB, + BC7_RGBA_UNORM_SRGB, + /* Depth Formats */ + D16_UNORM, + D24_UNORM, + D32_FLOAT, + D24_UNORM_S8_UINT, + D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + ASTC_4x4_UNORM, + ASTC_5x4_UNORM, + ASTC_5x5_UNORM, + ASTC_6x5_UNORM, + ASTC_6x6_UNORM, + ASTC_8x5_UNORM, + ASTC_8x6_UNORM, + ASTC_8x8_UNORM, + ASTC_10x5_UNORM, + ASTC_10x6_UNORM, + ASTC_10x8_UNORM, + ASTC_10x10_UNORM, + ASTC_12x10_UNORM, + ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + ASTC_4x4_UNORM_SRGB, + ASTC_5x4_UNORM_SRGB, + ASTC_5x5_UNORM_SRGB, + ASTC_6x5_UNORM_SRGB, + ASTC_6x6_UNORM_SRGB, + ASTC_8x5_UNORM_SRGB, + ASTC_8x6_UNORM_SRGB, + ASTC_8x8_UNORM_SRGB, + ASTC_10x5_UNORM_SRGB, + ASTC_10x6_UNORM_SRGB, + ASTC_10x8_UNORM_SRGB, + ASTC_10x10_UNORM_SRGB, + ASTC_12x10_UNORM_SRGB, + ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + ASTC_4x4_FLOAT, + ASTC_5x4_FLOAT, + ASTC_5x5_FLOAT, + ASTC_6x5_FLOAT, + ASTC_6x6_FLOAT, + ASTC_8x5_FLOAT, + ASTC_8x6_FLOAT, + ASTC_8x8_FLOAT, + ASTC_10x5_FLOAT, + ASTC_10x6_FLOAT, + ASTC_10x8_FLOAT, + ASTC_10x10_FLOAT, + ASTC_12x10_FLOAT, + ASTC_12x12_FLOAT, +} + +/** + * 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 + */ +public enum GPUTextureUsageFlags : Uint32 +{ + Sampler = (1u << 0), /**< Texture supports sampling. */ + ColorTarget = (1u << 1), /**< Texture is a color render target. */ + DepthStencilTarget = (1u << 2), /**< Texture is a depth stencil target. */ + GraphicsStorageRead = (1u << 3), /**< Texture supports storage reads in graphics stages. */ + ComputeStorageRead = (1u << 4), /**< Texture supports storage reads in the compute stage. */ + ComputeStorageWrite = (1u << 5), /**< Texture supports storage writes in the compute stage. */ + ComputeStorageSimultaneousReadWrite = (1u << 6), /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ +} /**< 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 + */ +[AllowDuplicates] public enum GPUTextureType : c_int +{ + _2d, /**< The texture is a 2-dimensional image. */ + _2dArray, /**< The texture is a 2-dimensional array image. */ + _3d, /**< The texture is a 3-dimensional image. */ + Cube, /**< The texture is a cube image. */ + CubeArray, /**< The texture is a cube array image. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUSampleCount : c_int +{ + _1, /**< No multisampling. */ + _2, /**< MSAA 2x */ + _4, /**< MSAA 4x */ + _8, /**< MSAA 8x */ +} + + +/** + * 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. + */ +[AllowDuplicates] public enum GPUCubeMapFace : c_int +{ + Positivex, + Negativex, + Positivey, + Negativey, + Positivez, + Negativez, +} + +/** + * 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 + */ +public enum GPUBufferUsageFlags : Uint32 +{ + Vertex = (1u << 0), /**< Buffer is a vertex buffer. */ + Index = (1u << 1), /**< Buffer is an index buffer. */ + Indirect = (1u << 2), /**< Buffer is an indirect buffer. */ + GraphicsStorageRead = (1u << 3), /**< Buffer supports storage reads in graphics stages. */ + ComputeStorageRead = (1u << 4), /**< Buffer supports storage reads in the compute stage. */ + ComputeStorageWrite = (1u << 5), /**< Buffer supports storage writes in the compute stage. */ +} /**< 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 + */ +[AllowDuplicates] public enum GPUTransferBufferUsage : c_int +{ + Upload, + Download, +} + +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ +[AllowDuplicates] public enum GPUShaderStage : c_int +{ + Vertex, + Fragment, +} + +/** + * 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 + */ +public enum GPUShaderFormat : Uint32 +{ + Invalid = 0, + Private = (1u << 0), /**< Shaders for NDA'd platforms. */ + Spirv = (1u << 1), /**< SPIR-V shaders for Vulkan. */ + Dxbc = (1u << 2), /**< DXBC SM5_1 shaders for D3D12. */ + Dxil = (1u << 3), /**< DXIL SM6_0 shaders for D3D12. */ + Msl = (1u << 4), /**< MSL shaders for Metal. */ + Metallib = (1u << 5), /**< Precompiled metallib shaders for Metal. */ +} /**< 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 + */ +[AllowDuplicates] public enum GPUVertexElementFormat : c_int +{ + Invalid, + + /* 32-bit Signed Integers */ + Int, + Int2, + Int3, + Int4, + + /* 32-bit Unsigned Integers */ + Uint, + Uint2, + Uint3, + Uint4, + + /* 32-bit Floats */ + Float, + Float2, + Float3, + Float4, + + /* 8-bit Signed Integers */ + Byte2, + Byte4, + + /* 8-bit Unsigned Integers */ + Ubyte2, + Ubyte4, + + /* 8-bit Signed Normalized */ + Byte2Norm, + Byte4Norm, + + /* 8-bit Unsigned Normalized */ + Ubyte2Norm, + Ubyte4Norm, + + /* 16-bit Signed Integers */ + Short2, + Short4, + + /* 16-bit Unsigned Integers */ + Ushort2, + Ushort4, + + /* 16-bit Signed Normalized */ + Short2Norm, + Short4Norm, + + /* 16-bit Unsigned Normalized */ + Ushort2Norm, + Ushort4Norm, + + /* 16-bit Floats */ + Half2, + Half4, +} + +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +[AllowDuplicates] public enum GPUVertexInputRate : c_int +{ + Vertex, /**< Attribute addressing is a function of the vertex index. */ + Instance, /**< Attribute addressing is a function of the instance index. */ +} + +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +[AllowDuplicates] public enum GPUFillMode : c_int +{ + Fill, /**< Polygons will be rendered via rasterization. */ + Line, /**< Polygon edges will be drawn as line segments. */ +} + +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +[AllowDuplicates] public enum GPUCullMode : c_int +{ + None, /**< No triangles are culled. */ + Front, /**< Front-facing triangles are culled. */ + Back, /**< Back-facing triangles are culled. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUFrontFace : c_int +{ + CounterClockwise, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + Clockwise, /**< A triangle with clockwise vertex winding will be considered front-facing. */ +} + +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +[AllowDuplicates] public enum GPUCompareOp : c_int +{ + Invalid, + Never, /**< The comparison always evaluates false. */ + Less, /**< The comparison evaluates reference < test. */ + Equal, /**< The comparison evaluates reference == test. */ + LessOrEqual, /**< The comparison evaluates reference <= test. */ + Greater, /**< The comparison evaluates reference > test. */ + NotEqual, /**< The comparison evaluates reference != test. */ + GreaterOrEqual, /**< The comparison evaluates reference >= test. */ + Always, /**< The comparison always evaluates true. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUStencilOp : c_int +{ + Invalid, + Keep, /**< Keeps the current value. */ + Zero, /**< Sets the value to 0. */ + Replace, /**< Sets the value to reference. */ + IncrementAndClamp, /**< Increments the current value and clamps to the maximum value. */ + DecrementAndClamp, /**< Decrements the current value and clamps to 0. */ + Invert, /**< Bitwise-inverts the current value. */ + IncrementAndWrap, /**< Increments the current value and wraps back to 0. */ + DecrementAndWrap, /**< Decrements the current value and wraps to the maximum value. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUBlendOp : c_int +{ + Invalid, + Add, /**< (source * source_factor) + (destination * destination_factor) */ + Subtract, /**< (source * source_factor) - (destination * destination_factor) */ + ReverseSubtract, /**< (destination * destination_factor) - (source * source_factor) */ + Min, /**< min(source, destination) */ + Max, /**< max(source, destination) */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUBlendFactor : c_int +{ + Invalid, + Zero, /**< 0 */ + One, /**< 1 */ + SrcColor, /**< source color */ + OneMinusSrcColor, /**< 1 - source color */ + DstColor, /**< destination color */ + OneMinusDstColor, /**< 1 - destination color */ + SrcAlpha, /**< source alpha */ + OneMinusSrcAlpha, /**< 1 - source alpha */ + DstAlpha, /**< destination alpha */ + OneMinusDstAlpha, /**< 1 - destination alpha */ + ConstantColor, /**< blend constant */ + OneMinusConstantColor, /**< 1 - blend constant */ + SrcAlphaSaturate, /**< min(source alpha, 1 - destination alpha) */ +} + +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +public enum GPUColorComponentFlags : Uint8 +{ + R = (1u << 0), /**< the red component */ + G = (1u << 1), /**< the green component */ + B = (1u << 2), /**< the blue component */ + A = (1u << 3), /**< the alpha component */ +} /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ +[AllowDuplicates] public enum GPUFilter : c_int +{ + Nearest, /**< Point filtering. */ + Linear, /**< Linear filtering. */ +} + +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ +[AllowDuplicates] public enum GPUSamplerMipmapMode : c_int +{ + Nearest, /**< Point filtering. */ + Linear, /**< Linear filtering. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUSamplerAddressMode : c_int +{ + Repeat, /**< Specifies that the coordinates will wrap around. */ + MirroredRepeat, /**< Specifies that the coordinates will wrap around mirrored. */ + ClampToEdge, /**< Specifies that the coordinates will clamp to the 0-1 range. */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUPresentMode : c_int +{ + Vsync, + Immediate, + Mailbox, +} + +/** + * 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 + */ +[AllowDuplicates] public enum GPUSwapchainComposition : c_int +{ + Sdr, + SdrLinear, + HdrExtendedLinear, + Hdr10St2084, +} + +/* Structures */ + +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ +[CRepr] public struct GPUViewport +{ + public float x; /**< The left offset of the viewport. */ + public float y; /**< The top offset of the viewport. */ + public float w; /**< The width of the viewport. */ + public float h; /**< The height of the viewport. */ + public float min_depth; /**< The minimum depth of the viewport. */ + public float max_depth; /**< The maximum depth of the viewport. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTextureTransferInfo +{ + public GPUTransferBuffer* transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + public Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + public Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + public Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTransferBufferLocation +{ + public GPUTransferBuffer* transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + public Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTextureLocation +{ + public GPUTexture* texture; /**< The texture used in the copy operation. */ + public Uint32 mip_level; /**< The mip level index of the location. */ + public Uint32 layer; /**< The layer index of the location. */ + public Uint32 x; /**< The left offset of the location. */ + public Uint32 y; /**< The top offset of the location. */ + public Uint32 z; /**< The front offset of the location. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTextureRegion +{ + public GPUTexture* texture; /**< The texture used in the copy operation. */ + public Uint32 mip_level; /**< The mip level index to transfer. */ + public Uint32 layer; /**< The layer index to transfer. */ + public Uint32 x; /**< The left offset of the region. */ + public Uint32 y; /**< The top offset of the region. */ + public Uint32 z; /**< The front offset of the region. */ + public Uint32 w; /**< The width of the region. */ + public Uint32 h; /**< The height of the region. */ + public Uint32 d; /**< The depth of the region. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUBlitRegion +{ + public GPUTexture* texture; /**< The texture. */ + public Uint32 mip_level; /**< The mip level index of the region. */ + public 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. */ + public Uint32 x; /**< The left offset of the region. */ + public Uint32 y; /**< The top offset of the region. */ + public Uint32 w; /**< The width of the region. */ + public Uint32 h; /**< The height of the region. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUBufferLocation +{ + public GPUBuffer* buffer; /**< The buffer. */ + public Uint32 offset; /**< The starting byte within the buffer. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUBufferRegion +{ + public GPUBuffer* buffer; /**< The buffer. */ + public Uint32 offset; /**< The starting byte within the buffer. */ + public Uint32 size; /**< The size in bytes of the region. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUIndirectDrawCommand +{ + public Uint32 num_vertices; /**< The number of vertices to draw. */ + public Uint32 num_instances; /**< The number of instances to draw. */ + public Uint32 first_vertex; /**< The index of the first vertex to draw. */ + public Uint32 first_instance; /**< The ID of the first instance to draw. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUIndexedIndirectDrawCommand +{ + public Uint32 num_indices; /**< The number of indices to draw per instance. */ + public Uint32 num_instances; /**< The number of instances to draw. */ + public Uint32 first_index; /**< The base index within the index buffer. */ + public Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + public Uint32 first_instance; /**< The ID of the first instance to draw. */ +} + +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ +[CRepr] public struct GPUIndirectDispatchCommand +{ + public Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + public Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + public Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ +} + +/* 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 + */ +[CRepr] public struct GPUSamplerCreateInfo +{ + public GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + public GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + public GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + public GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + public GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + public GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + public float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + public float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + public GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + public float min_lod; /**< Clamps the minimum of the computed LOD value. */ + public float max_lod; /**< Clamps the maximum of the computed LOD value. */ + public bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + public bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + public Uint8 padding1; + public Uint8 padding2; + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUVertexBufferDescription +{ + public Uint32 slot; /**< The binding slot of the vertex buffer. */ + public Uint32 pitch; /**< The size of a single element + the offset between elements. */ + public GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + public Uint32 instance_step_rate; /**< Reserved for future use. Must be set to 0. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUVertexAttribute +{ + public Uint32 location; /**< The shader input location index. */ + public Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + public GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + public Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUVertexInputState +{ + public GPUVertexBufferDescription* vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + public Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + public GPUVertexAttribute* vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + public Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ +} + +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ +[CRepr] public struct GPUStencilOpState +{ + public GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + public GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + public GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + public GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUColorTargetBlendState +{ + public GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + public GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + public GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + public GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + public GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + public GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + public 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. */ + public bool enable_blend; /**< Whether blending is enabled for the color target. */ + public bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + public Uint8 padding1; + public Uint8 padding2; +} + + +/** + * 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 + */ +[CRepr] public struct GPUShaderCreateInfo +{ + public c_size code_size; /**< The size in bytes of the code pointed to. */ + public Uint8* code; /**< A pointer to shader code. */ + public c_char* entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + public GPUShaderFormat format; /**< The format of the shader code. */ + public GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + public Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + public Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + public Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + public Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTextureCreateInfo +{ + public GPUTextureType type; /**< The base dimensionality of the texture. */ + public GPUTextureFormat format; /**< The pixel format of the texture. */ + public GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + public Uint32 width; /**< The width of the texture. */ + public Uint32 height; /**< The height of the texture. */ + public 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. */ + public Uint32 num_levels; /**< The number of mip levels in the texture. */ + public GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUBufferCreateInfo +{ + public GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + public Uint32 size; /**< The size in bytes of the buffer. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ +[CRepr] public struct GPUTransferBufferCreateInfo +{ + public GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + public Uint32 size; /**< The size in bytes of the transfer buffer. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/* 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 + */ +[CRepr] public struct GPURasterizerState +{ + public GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + public GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + public GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + public float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + public float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + public float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + public bool enable_depth_bias; /**< true to bias fragment depth values. */ + public bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + public Uint8 padding1; + public Uint8 padding2; +} + +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +[CRepr] public struct GPUMultisampleState +{ + public GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + public Uint32 sample_mask; /**< Reserved for future use. Must be set to 0. */ + public bool enable_mask; /**< Reserved for future use. Must be set to false. */ + public bool enable_alpha_to_coverage; /**< true enables the alpha-to-coverage feature. */ + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * 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 + */ +[CRepr] public struct GPUDepthStencilState +{ + public GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + public GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + public GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + public Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + public Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + public bool enable_depth_test; /**< true enables the depth test. */ + public bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + public bool enable_stencil_test; /**< true enables the stencil test. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * 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 + */ +[CRepr] public struct GPUColorTargetDescription +{ + public GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + public GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUGraphicsPipelineTargetInfo +{ + public GPUColorTargetDescription* color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + public Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + public GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + public bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * 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 + */ +[CRepr] public struct GPUGraphicsPipelineCreateInfo +{ + public GPUShader* vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + public GPUShader* fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + public GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + public GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + public GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + public GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + public GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + public GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUComputePipelineCreateInfo +{ + public c_size code_size; /**< The size in bytes of the compute shader code pointed to. */ + public Uint8* code; /**< A pointer to compute shader code. */ + public c_char* entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + public GPUShaderFormat format; /**< The format of the compute shader code. */ + public Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + public Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + public Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + public Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + public Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + public Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + public Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + public Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + public Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUColorTargetInfo +{ + public GPUTexture* texture; /**< The texture that will be used as a color target by a render pass. */ + public Uint32 mip_level; /**< The mip level to use as a color target. */ + public 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. */ + public 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. */ + public GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + public GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + public GPUTexture* resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + public 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. */ + public 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. */ + public bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + public bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + public Uint8 padding1; + public Uint8 padding2; +} + +/** + * 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 + */ +[CRepr] public struct GPUDepthStencilTargetInfo +{ + public GPUTexture* texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + public 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. */ + public GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + public GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + public GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + public GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + public bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + public 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. */ + public Uint8 mip_level; /**< The mip level to use as the depth stencil target. */ + public Uint8 layer; /**< The layer index to use as the depth stencil target. */ +} + +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +[CRepr] public struct GPUBlitInfo { + public GPUBlitRegion source; /**< The source region for the blit. */ + public GPUBlitRegion destination; /**< The destination region for the blit. */ + public GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + public FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + public FlipMode flip_mode; /**< The flip mode for the source region. */ + public GPUFilter filter; /**< The filter mode used when blitting. */ + public bool cycle; /**< true cycles the destination texture if it is already bound. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/* 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 + */ +[CRepr] public struct GPUBufferBinding +{ + public 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. */ + public Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUTextureSamplerBinding +{ + public GPUTexture* texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + public GPUSampler* sampler; /**< The sampler to bind. */ +} + +/** + * 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 + */ +[CRepr] public struct GPUStorageBufferReadWriteBinding +{ + public GPUBuffer* buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + public bool cycle; /**< true cycles the buffer if it is already bound. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/** + * 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 + */ +[CRepr] public struct GPUStorageTextureReadWriteBinding +{ + public 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. */ + public Uint32 mip_level; /**< The mip level index to bind. */ + public Uint32 layer; /**< The layer index to bind. */ + public bool cycle; /**< true cycles the texture if it is already bound. */ + public Uint8 padding1; + public Uint8 padding2; + public Uint8 padding3; +} + +/* 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 + */ +[LinkName("SDL_GPUSupportsShaderFormats")] public static extern bool GPUSupportsShaderFormats(GPUShaderFormat format_flags, c_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 + */ +[LinkName("SDL_GPUSupportsProperties")] public static extern bool GPUSupportsProperties(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 + */ +[LinkName("SDL_CreateGPUDevice")] public static extern GPUDevice* CreateGPUDevice(GPUShaderFormat format_flags, bool debug_mode, c_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. + * + * 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 + */ +[LinkName("SDL_CreateGPUDeviceWithProperties")] public static extern GPUDevice* CreateGPUDeviceWithProperties(PropertiesID props); + +public const let PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN = "SDL.gpu.device.create.debugmode"; +public const let PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN = "SDL.gpu.device.create.preferlowpower"; +public const let PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN = "SDL.gpu.device.create.verbose"; +public const let PROP_GPU_DEVICE_CREATE_NAME_STRING = "SDL.gpu.device.create.name"; +public const let PROP_GPU_DEVICE_CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN = "SDL.gpu.device.create.feature.clip_distance"; +public const let PROP_GPU_DEVICE_CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN = "SDL.gpu.device.create.feature.depth_clamping"; +public const let PROP_GPU_DEVICE_CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN = "SDL.gpu.device.create.feature.indirect_draw_first_instance"; +public const let PROP_GPU_DEVICE_CREATE_FEATURE_ANISOTROPY_BOOLEAN = "SDL.gpu.device.create.feature.anisotropy"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN = "SDL.gpu.device.create.shaders.private"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN = "SDL.gpu.device.create.shaders.spirv"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN = "SDL.gpu.device.create.shaders.dxbc"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN = "SDL.gpu.device.create.shaders.dxil"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN = "SDL.gpu.device.create.shaders.msl"; +public const let PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN = "SDL.gpu.device.create.shaders.metallib"; +public const let PROP_GPU_DEVICE_CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN = "SDL.gpu.device.create.d3d12.allowtier1resourcebinding"; +public const let PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING = "SDL.gpu.device.create.d3d12.semantic"; +public const let PROP_GPU_DEVICE_CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN = "SDL.gpu.device.create.vulkan.requirehardwareacceleration"; +public const let PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER = "SDL.gpu.device.create.vulkan.options"; +public const let PROP_GPU_DEVICE_CREATE_METAL_ALLOW_MACFAMILY1_BOOLEAN = "SDL.gpu.device.create.metal.allowmacfamily1"; + +public const let PROP_GPU_DEVICE_CREATE_XR_ENABLE_BOOLEAN = "SDL.gpu.device.create.xr.enable"; +public const let PROP_GPU_DEVICE_CREATE_XR_INSTANCE_POINTER = "SDL.gpu.device.create.xr.instance_out"; +public const let PROP_GPU_DEVICE_CREATE_XR_SYSTEM_ID_POINTER = "SDL.gpu.device.create.xr.system_id_out"; +public const let PROP_GPU_DEVICE_CREATE_XR_VERSION_NUMBER = "SDL.gpu.device.create.xr.version"; +public const let PROP_GPU_DEVICE_CREATE_XR_FORM_FACTOR_NUMBER = "SDL.gpu.device.create.xr.form_factor"; +public const let PROP_GPU_DEVICE_CREATE_XR_EXTENSION_COUNT_NUMBER = "SDL.gpu.device.create.xr.extensions.count"; +public const let PROP_GPU_DEVICE_CREATE_XR_EXTENSION_NAMES_POINTER = "SDL.gpu.device.create.xr.extensions.names"; +public const let PROP_GPU_DEVICE_CREATE_XR_LAYER_COUNT_NUMBER = "SDL.gpu.device.create.xr.layers.count"; +public const let PROP_GPU_DEVICE_CREATE_XR_LAYER_NAMES_POINTER = "SDL.gpu.device.create.xr.layers.names"; +public const let PROP_GPU_DEVICE_CREATE_XR_APPLICATION_NAME_STRING = "SDL.gpu.device.create.xr.application.name"; +public const let PROP_GPU_DEVICE_CREATE_XR_APPLICATION_VERSION_NUMBER = "SDL.gpu.device.create.xr.application.version"; +public const let PROP_GPU_DEVICE_CREATE_XR_ENGINE_NAME_STRING = "SDL.gpu.device.create.xr.engine.name"; +public const let PROP_GPU_DEVICE_CREATE_XR_ENGINE_VERSION_NUMBER = "SDL.gpu.device.create.xr.engine.version"; + + +/** + * 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. + */ +[CRepr] public struct GPUVulkanOptions +{ + public Uint32 vulkan_api_version; /**< The Vulkan API version to request for the instance. Use Vulkan's VK_MAKE_VERSION or VK_MAKE_API_VERSION. */ + public void* feature_list; /**< Pointer to the first element of a chain of Vulkan feature structs. (Requires API version 1.1 or higher.)*/ + public void* vulkan_10_physical_device_features; /**< Pointer to a VkPhysicalDeviceFeatures struct to enable additional Vulkan 1.0 features. */ + public Uint32 device_extension_count; /**< Number of additional device extensions to require. */ + public c_char** device_extension_names; /**< Pointer to a list of additional device extensions to require. */ + public Uint32 instance_extension_count; /**< Number of additional instance extensions to require. */ + public c_char** instance_extension_names; /**< Pointer to a list of additional instance extensions to require. */ +} + +/** + * 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 + */ +[LinkName("SDL_DestroyGPUDevice")] public static extern void DestroyGPUDevice(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 + */ +[LinkName("SDL_GetNumGPUDrivers")] public static extern c_int GetNumGPUDrivers(); + +/** + * 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 + */ +[LinkName("SDL_GetGPUDriver")] public static extern c_char* GetGPUDriver(c_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. + */ +[LinkName("SDL_GetGPUDeviceDriver")] public static extern c_char* GetGPUDeviceDriver(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. + */ +[LinkName("SDL_GetGPUShaderFormats")] public static extern GPUShaderFormat GetGPUShaderFormats(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. + */ +[LinkName("SDL_GetGPUDeviceProperties")] public static extern PropertiesID GetGPUDeviceProperties(GPUDevice* device); + +public const let PROP_GPU_DEVICE_NAME_STRING = "SDL.gpu.device.name"; +public const let PROP_GPU_DEVICE_DRIVER_NAME_STRING = "SDL.gpu.device.driver_name"; +public const let PROP_GPU_DEVICE_DRIVER_VERSION_STRING = "SDL.gpu.device.driver_version"; +public const let 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 + */ +[LinkName("SDL_CreateGPUComputePipeline")] public static extern GPUComputePipeline* CreateGPUComputePipeline(GPUDevice* device, GPUComputePipelineCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_CreateGPUGraphicsPipeline")] public static extern GPUGraphicsPipeline* CreateGPUGraphicsPipeline(GPUDevice* device, GPUGraphicsPipelineCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_CreateGPUSampler")] public static extern GPUSampler* CreateGPUSampler(GPUDevice* device, GPUSamplerCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_CreateGPUShader")] public static extern GPUShader* CreateGPUShader(GPUDevice* device, GPUShaderCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_CreateGPUTexture")] public static extern GPUTexture* CreateGPUTexture(GPUDevice* device, GPUTextureCreateInfo* createinfo); + +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT = "SDL.gpu.texture.create.d3d12.clear.r"; +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT = "SDL.gpu.texture.create.d3d12.clear.g"; +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT = "SDL.gpu.texture.create.d3d12.clear.b"; +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT = "SDL.gpu.texture.create.d3d12.clear.a"; +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT = "SDL.gpu.texture.create.d3d12.clear.depth"; +public const let PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER = "SDL.gpu.texture.create.d3d12.clear.stencil"; +public const let 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 + */ +[LinkName("SDL_CreateGPUBuffer")] public static extern GPUBuffer* CreateGPUBuffer(GPUDevice* device, GPUBufferCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_CreateGPUTransferBuffer")] public static extern GPUTransferBuffer* CreateGPUTransferBuffer(GPUDevice* device, GPUTransferBufferCreateInfo* createinfo); + +public const let 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 + */ +[LinkName("SDL_SetGPUBufferName")] public static extern void SetGPUBufferName(GPUDevice* device, GPUBuffer* buffer, c_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 + */ +[LinkName("SDL_SetGPUTextureName")] public static extern void SetGPUTextureName(GPUDevice* device, GPUTexture* texture, c_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. + */ +[LinkName("SDL_InsertGPUDebugLabel")] public static extern void InsertGPUDebugLabel(GPUCommandBuffer* command_buffer, c_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 + */ +[LinkName("SDL_PushGPUDebugGroup")] public static extern void PushGPUDebugGroup(GPUCommandBuffer* command_buffer, c_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 + */ +[LinkName("SDL_PopGPUDebugGroup")] public static extern void PopGPUDebugGroup(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. + */ +[LinkName("SDL_ReleaseGPUTexture")] public static extern void ReleaseGPUTexture(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUSampler")] public static extern void ReleaseGPUSampler(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUBuffer")] public static extern void ReleaseGPUBuffer(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUTransferBuffer")] public static extern void ReleaseGPUTransferBuffer(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUComputePipeline")] public static extern void ReleaseGPUComputePipeline(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUShader")] public static extern void ReleaseGPUShader(GPUDevice* device, 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. + */ +[LinkName("SDL_ReleaseGPUGraphicsPipeline")] public static extern void ReleaseGPUGraphicsPipeline(GPUDevice* device, 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 + */ +[LinkName("SDL_AcquireGPUCommandBuffer")] public static extern GPUCommandBuffer* AcquireGPUCommandBuffer(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. + */ +[LinkName("SDL_PushGPUVertexUniformData")] public static extern void PushGPUVertexUniformData(GPUCommandBuffer* command_buffer, Uint32 slot_index, 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. + */ +[LinkName("SDL_PushGPUFragmentUniformData")] public static extern void PushGPUFragmentUniformData(GPUCommandBuffer* command_buffer, Uint32 slot_index, 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. + */ +[LinkName("SDL_PushGPUComputeUniformData")] public static extern void PushGPUComputeUniformData(GPUCommandBuffer* command_buffer, Uint32 slot_index, 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 + */ +[LinkName("SDL_BeginGPURenderPass")] public static extern GPURenderPass* BeginGPURenderPass(GPUCommandBuffer* command_buffer, GPUColorTargetInfo* color_target_infos, Uint32 num_color_targets, 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. + */ +[LinkName("SDL_BindGPUGraphicsPipeline")] public static extern void BindGPUGraphicsPipeline(GPURenderPass* render_pass, 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. + */ +[LinkName("SDL_SetGPUViewport")] public static extern void SetGPUViewport(GPURenderPass* render_pass, 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. + */ +[LinkName("SDL_SetGPUScissor")] public static extern void SetGPUScissor(GPURenderPass* render_pass, 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 + */ +[LinkName("SDL_SetGPUBlendConstants")] public static extern void SetGPUBlendConstants(GPURenderPass* render_pass, 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. + */ +[LinkName("SDL_SetGPUStencilReference")] public static extern void SetGPUStencilReference(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. + */ +[LinkName("SDL_BindGPUVertexBuffers")] public static extern void BindGPUVertexBuffers(GPURenderPass* render_pass, Uint32 first_slot, 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. + */ +[LinkName("SDL_BindGPUIndexBuffer")] public static extern void BindGPUIndexBuffer(GPURenderPass* render_pass, GPUBufferBinding* binding, 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 + */ +[LinkName("SDL_BindGPUVertexSamplers")] public static extern void BindGPUVertexSamplers(GPURenderPass* render_pass, Uint32 first_slot, 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 + */ +[LinkName("SDL_BindGPUVertexStorageTextures")] public static extern void BindGPUVertexStorageTextures(GPURenderPass* render_pass, Uint32 first_slot, GPUTexture** 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 + */ +[LinkName("SDL_BindGPUVertexStorageBuffers")] public static extern void BindGPUVertexStorageBuffers(GPURenderPass* render_pass, Uint32 first_slot, GPUBuffer** 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 + */ +[LinkName("SDL_BindGPUFragmentSamplers")] public static extern void BindGPUFragmentSamplers(GPURenderPass* render_pass, Uint32 first_slot, 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 + */ +[LinkName("SDL_BindGPUFragmentStorageTextures")] public static extern void BindGPUFragmentStorageTextures(GPURenderPass* render_pass, Uint32 first_slot, GPUTexture** 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 + */ +[LinkName("SDL_BindGPUFragmentStorageBuffers")] public static extern void BindGPUFragmentStorageBuffers(GPURenderPass* render_pass, Uint32 first_slot, GPUBuffer** 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. + */ +[LinkName("SDL_DrawGPUIndexedPrimitives")] public static extern void DrawGPUIndexedPrimitives(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. + */ +[LinkName("SDL_DrawGPUPrimitives")] public static extern void DrawGPUPrimitives(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. + */ +[LinkName("SDL_DrawGPUPrimitivesIndirect")] public static extern void DrawGPUPrimitivesIndirect(GPURenderPass* render_pass, 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. + */ +[LinkName("SDL_DrawGPUIndexedPrimitivesIndirect")] public static extern void DrawGPUIndexedPrimitivesIndirect(GPURenderPass* render_pass, 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. + */ +[LinkName("SDL_EndGPURenderPass")] public static extern void EndGPURenderPass(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 + */ +[LinkName("SDL_BeginGPUComputePass")] public static extern GPUComputePass* BeginGPUComputePass(GPUCommandBuffer* command_buffer, GPUStorageTextureReadWriteBinding* storage_texture_bindings, Uint32 num_storage_texture_bindings, 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. + */ +[LinkName("SDL_BindGPUComputePipeline")] public static extern void BindGPUComputePipeline(GPUComputePass* compute_pass, 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 + */ +[LinkName("SDL_BindGPUComputeSamplers")] public static extern void BindGPUComputeSamplers(GPUComputePass* compute_pass, Uint32 first_slot, 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 + */ +[LinkName("SDL_BindGPUComputeStorageTextures")] public static extern void BindGPUComputeStorageTextures(GPUComputePass* compute_pass, Uint32 first_slot, GPUTexture** 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 + */ +[LinkName("SDL_BindGPUComputeStorageBuffers")] public static extern void BindGPUComputeStorageBuffers(GPUComputePass* compute_pass, Uint32 first_slot, GPUBuffer** 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. + */ +[LinkName("SDL_DispatchGPUCompute")] public static extern void DispatchGPUCompute(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. + */ +[LinkName("SDL_DispatchGPUComputeIndirect")] public static extern void DispatchGPUComputeIndirect(GPUComputePass* compute_pass, 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. + */ +[LinkName("SDL_EndGPUComputePass")] public static extern void EndGPUComputePass(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. + */ +[LinkName("SDL_MapGPUTransferBuffer")] public static extern void* MapGPUTransferBuffer(GPUDevice* device, 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. + */ +[LinkName("SDL_UnmapGPUTransferBuffer")] public static extern void UnmapGPUTransferBuffer(GPUDevice* device, 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 + */ +[LinkName("SDL_BeginGPUCopyPass")] public static extern GPUCopyPass* BeginGPUCopyPass(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. + */ +[LinkName("SDL_UploadToGPUTexture")] public static extern void UploadToGPUTexture(GPUCopyPass* copy_pass, GPUTextureTransferInfo* source, 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. + */ +[LinkName("SDL_UploadToGPUBuffer")] public static extern void UploadToGPUBuffer(GPUCopyPass* copy_pass, GPUTransferBufferLocation* source, 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. + */ +[LinkName("SDL_CopyGPUTextureToTexture")] public static extern void CopyGPUTextureToTexture(GPUCopyPass* copy_pass, GPUTextureLocation* source, 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. + */ +[LinkName("SDL_CopyGPUBufferToBuffer")] public static extern void CopyGPUBufferToBuffer(GPUCopyPass* copy_pass, GPUBufferLocation* source, 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. + */ +[LinkName("SDL_DownloadFromGPUTexture")] public static extern void DownloadFromGPUTexture(GPUCopyPass* copy_pass, GPUTextureRegion* source, 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. + */ +[LinkName("SDL_DownloadFromGPUBuffer")] public static extern void DownloadFromGPUBuffer(GPUCopyPass* copy_pass, GPUBufferRegion* source, GPUTransferBufferLocation* destination); + +/** + * Ends the current copy pass. + * + * \param copy_pass a copy pass handle. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_EndGPUCopyPass")] public static extern void EndGPUCopyPass(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. + */ +[LinkName("SDL_GenerateMipmapsForGPUTexture")] public static extern void GenerateMipmapsForGPUTexture(GPUCommandBuffer* command_buffer, 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. + */ +[LinkName("SDL_BlitGPUTexture")] public static extern void BlitGPUTexture(GPUCommandBuffer* command_buffer, 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 + */ +[LinkName("SDL_WindowSupportsGPUSwapchainComposition")] public static extern bool WindowSupportsGPUSwapchainComposition(GPUDevice* device, Window* window, 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 + */ +[LinkName("SDL_WindowSupportsGPUPresentMode")] public static extern bool WindowSupportsGPUPresentMode(GPUDevice* device, Window* window, 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 + */ +[LinkName("SDL_ClaimWindowForGPUDevice")] public static extern bool ClaimWindowForGPUDevice(GPUDevice* device, 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 + */ +[LinkName("SDL_ReleaseWindowFromGPUDevice")] public static extern void ReleaseWindowFromGPUDevice(GPUDevice* device, 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 + */ +[LinkName("SDL_SetGPUSwapchainParameters")] public static extern bool SetGPUSwapchainParameters(GPUDevice* device, Window* window, GPUSwapchainComposition swapchain_composition, 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. + */ +[LinkName("SDL_SetGPUAllowedFramesInFlight")] public static extern bool SetGPUAllowedFramesInFlight(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. + */ +[LinkName("SDL_GetGPUSwapchainTextureFormat")] public static extern GPUTextureFormat GetGPUSwapchainTextureFormat(GPUDevice* device, 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 + */ +[LinkName("SDL_AcquireGPUSwapchainTexture")] public static extern bool AcquireGPUSwapchainTexture(GPUCommandBuffer* command_buffer, Window* window, out GPUTexture* swapchain_texture, out Uint32 swapchain_texture_width, out 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 + */ +[LinkName("SDL_WaitForGPUSwapchain")] public static extern bool WaitForGPUSwapchain(GPUDevice* device, 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 + */ +[LinkName("SDL_WaitAndAcquireGPUSwapchainTexture")] public static extern bool WaitAndAcquireGPUSwapchainTexture(GPUCommandBuffer* command_buffer, Window* window, out GPUTexture* swapchain_texture, out Uint32 swapchain_texture_width, out 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 + */ +[LinkName("SDL_SubmitGPUCommandBuffer")] public static extern bool SubmitGPUCommandBuffer(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 + */ +[LinkName("SDL_SubmitGPUCommandBufferAndAcquireFence")] public static extern GPUFence* SubmitGPUCommandBufferAndAcquireFence(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 + */ +[LinkName("SDL_CancelGPUCommandBuffer")] public static extern bool CancelGPUCommandBuffer(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 + */ +[LinkName("SDL_WaitForGPUIdle")] public static extern bool WaitForGPUIdle(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 + */ +[LinkName("SDL_WaitForGPUFences")] public static extern bool WaitForGPUFences(GPUDevice* device, bool wait_all, GPUFence** 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 + */ +[LinkName("SDL_QueryGPUFence")] public static extern bool QueryGPUFence(GPUDevice* device, 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 + */ +[LinkName("SDL_ReleaseGPUFence")] public static extern void ReleaseGPUFence(GPUDevice* device, 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 + */ +[LinkName("SDL_GPUTextureFormatTexelBlockSize")] public static extern Uint32 GPUTextureFormatTexelBlockSize(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. + */ +[LinkName("SDL_GPUTextureSupportsFormat")] public static extern bool GPUTextureSupportsFormat(GPUDevice* device, GPUTextureFormat format, GPUTextureType type, 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. + */ +[LinkName("SDL_GPUTextureSupportsSampleCount")] public static extern bool GPUTextureSupportsSampleCount(GPUDevice* device, GPUTextureFormat format, 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. + */ +[LinkName("SDL_CalculateGPUTextureFormatSize")] public static extern Uint32 CalculateGPUTextureFormatSize(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. + */ +[LinkName("SDL_GetPixelFormatFromGPUTextureFormat")] public static extern PixelFormat GetPixelFormatFromGPUTextureFormat(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. + */ +[LinkName("SDL_GetGPUTextureFormatFromPixelFormat")] public static extern GPUTextureFormat GetGPUTextureFormatFromPixelFormat(PixelFormat format); +} + +/** + * 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 + */ + + +/** + * 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 + */ + + +/* SDL_PLATFORM_GDK */ + + + +/* __cplusplus */ + + +/* SDL_gpu_h_ */ \ No newline at end of file diff --git a/src/SDL_guid.bf b/src/SDL_guid.bf new file mode 100644 index 0000000..a73a0bb --- /dev/null +++ b/src/SDL_guid.bf @@ -0,0 +1,117 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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: GUID */ + +/** + * # CategoryGUID + * + * 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + * + * 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 + * controllers from the same vendor with the same product ID and revision may + * have the same GUID. + * + * 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. + */ +[CRepr] public struct GUID { + public Uint8[16] data; +} + +/* Function prototypes */ + +/** + * Get an ASCII string representation for a given SDL_GUID. + * + * \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, should be at least 33 bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StringToGUID + */ +[LinkName("SDL_GUIDToString")] public static extern void GUIDToString(GUID guid, c_char* pszGUID, c_int cbGUID); + +/** + * Convert a GUID string into a SDL_GUID 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_GUID structure. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GUIDToString + */ +[LinkName("SDL_StringToGUID")] public static extern GUID StringToGUID(c_char* pchGUID); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_guid_h_ */ \ No newline at end of file diff --git a/src/SDL_haptic.bf b/src/SDL_haptic.bf new file mode 100644 index 0000000..f518bfb --- /dev/null +++ b/src/SDL_haptic.bf @@ -0,0 +1,1472 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryHaptic + * + * 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_OpenHaptic() to open from index. + * - SDL_OpenHapticFromJoystick() to open from an existing joystick. + * - Create an effect (SDL_HapticEffect). + * - 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 = NULL; + * + * // Open the device + * SDL_HapticID *haptics = SDL_GetHaptics(NULL); + * if (haptics) { + * haptic = SDL_OpenHaptic(haptics[0]); + * SDL_free(haptics); + * } + * if (haptic == NULL) + * return; + * + * // Initialize simple rumble + * if (!SDL_InitHapticRumble(haptic)) + * return; + * + * // Play effect at 50% strength for 2 seconds + * if (!SDL_PlayHapticRumble(haptic, 0.5, 2000)) + * return; + * SDL_Delay(2000); + * + * // Clean up + * SDL_CloseHaptic(haptic); + * ``` + * + * Complete example: + * + * ```c + * bool test_haptic(SDL_Joystick *joystick) + * { + * SDL_Haptic *haptic; + * SDL_HapticEffect effect; + * SDL_HapticEffectID effect_id; + * + * // Open the device + * haptic = SDL_OpenHapticFromJoystick(joystick); + * if (haptic == NULL) return false; // Most likely joystick isn't haptic + * + * // See if it can do sine waves + * 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 + * effect.type = SDL_HAPTIC_SINE; + * effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates + * effect.periodic.direction.dir[0] = 18000; // Force comes from south + * effect.periodic.period = 1000; // 1000 ms + * effect.periodic.magnitude = 20000; // 20000/32767 strength + * effect.periodic.length = 5000; // 5 seconds long + * effect.periodic.attack_length = 1000; // Takes 1 second to get max strength + * effect.periodic.fade_length = 1000; // Takes 1 second to fade away + * + * // Upload the effect + * effect_id = SDL_CreateHapticEffect(haptic, &effect); + * + * // Test the effect + * 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_DestroyHapticEffect(haptic, effect_id); + * + * // Close the device + * SDL_CloseHaptic(haptic); + * + * return true; // Success + * } + * ``` + * + * Note that the SDL haptic subsystem is not thread-safe. + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + +/* __cplusplus */ + +/* 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. + * + * Some platforms may have higher precision than that (Linux FF, Windows XInput) + * so we should fix the inconsistency in favor of higher possible precision, + * adjusting for platforms that use different scales. + * -flibit + */ + +/** + * The haptic structure used to identify an SDL haptic. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic + */ +[CRepr] public struct 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 + */ +public const let HAPTIC_INFINITY = 4294967295U; + + +/** + * \name Haptic features + * + * Different haptic features a device can have. + */ +/* @{ */ + +/** + * \name Haptic effects + */ +/* @{ */ + +/** + * Type of haptic effect. + */ +public typealias HapticEffectType = Uint16; + +/** + * Constant effect supported. + * + * Constant haptic effect. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + */ +public const let 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 + */ +public const let HAPTIC_SINE = (1u<<1); + +/** + * Square wave effect supported. + * + * Periodic haptic effect that simulates square waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + */ +public const let 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 + */ +public const let 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 + */ +public const let 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 + */ +public const let HAPTIC_SAWTOOTHDOWN = (1u<<5); + +/** + * Ramp effect supported. + * + * Ramp haptic effect. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticRamp + */ +public const let HAPTIC_RAMP = (1u<<6); + +/** + * Spring effect supported - uses axes position. + * + * 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 + */ +public const let HAPTIC_SPRING = (1u<<7); + +/** + * Damper effect supported - uses axes velocity. + * + * 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 + */ +public const let HAPTIC_DAMPER = (1u<<8); + +/** + * Inertia effect supported - uses axes acceleration. + * + * 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 + */ +public const let HAPTIC_INERTIA = (1u<<9); + +/** + * Friction effect supported - uses axes movement. + * + * 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 + */ +public const let 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 + */ +public const let HAPTIC_LEFTRIGHT = (1u<<11); + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let HAPTIC_RESERVED1 = (1u<<12); + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let HAPTIC_RESERVED2 = (1u<<13); + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let HAPTIC_RESERVED3 = (1u<<14); + +/** + * Custom effect is supported. + * + * User defined custom haptic effect. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let HAPTIC_CUSTOM = (1u<<15); + +/* @} */ /* Haptic effects */ + +/* These last few are features the device has, not effects */ + +/** + * Device can set global gain. + * + * Device supports setting the global gain. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticGain + */ +public const let HAPTIC_GAIN = (1u<<16); + +/** + * Device can set autocenter. + * + * Device supports setting autocenter. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticAutocenter + */ +public const let HAPTIC_AUTOCENTER = (1u<<17); + +/** + * Device can be queried for effect status. + * + * Device supports querying effect status. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetHapticEffectStatus + */ +public const let HAPTIC_STATUS = (1u<<18); + +/** + * Device can be paused. + * + * Devices supports being paused. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PauseHaptic + * \sa SDL_ResumeHaptic + */ +public const let HAPTIC_PAUSE = (1u<<19); + + +/** + * \name Direction encodings + */ +/* @{ */ + +/** + * Type of coordinates used for haptic direction. + */ +public typealias HapticDirectionType = Uint8; + +/** + * Uses polar coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + */ +public const let HAPTIC_POLAR = 0; + +/** + * Uses cartesian coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + */ +public const let HAPTIC_CARTESIAN = 1; + +/** + * Uses spherical coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + */ +public const let HAPTIC_SPHERICAL = 2; + +/** + * Use this value to play an effect on the steering wheel axis. + * + * 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 + */ +public const let HAPTIC_STEERING_AXIS = 3; + +/* @} */ /* Direction encodings */ + +/* @} */ /* Haptic features */ + + +/** + * ID for haptic effects. + * + * This is -1 if the ID is invalid. + * + * \sa SDL_CreateHapticEffect + */ +public typealias HapticEffectID = c_int; + + +/** + * Structure that represents a haptic direction. + * + * This is the direction where the force comes from, instead of the direction + * in which the force is exerted. + * + * Directions can be specified by: + * + * - SDL_HAPTIC_POLAR : Specified by polar coordinates. + * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. + * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. + * + * Cardinal directions of the haptic device are relative to the positioning of + * the device. North is considered to be away from the user. + * + * The following diagram represents the cardinal directions: + * + * ``` + * .--. + * |__| .-------. + * |=.| |.-----.| + * |--| || || + * | | |'-----'| + * |__|~')_____(' + * [ COMPUTER ] + * + * + * North (0,-1) + * ^ + * | + * | + * (-1,0) West <----[ HAPTIC ]----> East (1,0) + * | + * | + * v + * South (0,1) + * + * + * [ USER ] + * \|||/ + * (o o) + * ---ooO-(_)-Ooo--- + * ``` + * + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree + * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first + * `dir` parameter. The cardinal directions would be: + * + * - North: 0 (0 degrees) + * - East: 9000 (90 degrees) + * - South: 18000 (180 degrees) + * - West: 27000 (270 degrees) + * + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X + * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first + * three `dir` parameters. The cardinal directions would be: + * + * - North: 0,-1, 0 + * - East: 1, 0, 0 + * - South: 0, 1, 0 + * - West: -1, 0, 0 + * + * The Z axis represents the height of the effect if supported, otherwise it's + * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can + * use any multiple you want, only the direction matters. + * + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The + * first two `dir` parameters are used. The `dir` parameters are as follows + * (all values are in hundredths of degrees): + * + * - Degrees from (1, 0) rotated towards (0, 1). + * - Degrees towards (0, 0, 1) (device needs at least 3 axes). + * + * Example of force coming from the south with all encodings (force coming + * from the south means the user will have to pull the stick to counteract): + * + * ```c + * SDL_HapticDirection direction; + * + * // Cartesian directions + * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding. + * direction.dir[0] = 0; // X position + * direction.dir[1] = 1; // Y position + * // Assuming the device has 2 axes, we don't need to specify third parameter. + * + * // Polar directions + * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding. + * direction.dir[0] = 18000; // Polar only uses first parameter + * + * // Spherical coordinates + * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding + * 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_GetNumHapticAxes + */ +[CRepr] public struct HapticDirection +{ + public HapticDirectionType type; /**< The type of encoding. */ + public Sint32[3] dir; /**< The encoded direction. */ +} + + +/** + * A structure containing a template for a Constant effect. + * + * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. + * + * 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 + */ +[CRepr] public struct HapticConstant +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_CONSTANT */ + public HapticDirection direction; /**< Direction of the effect. */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect. */ + public Uint16 delay; /**< Delay before starting the effect. */ + + /* Trigger */ + public Uint16 button; /**< Button that triggers the effect. */ + public Uint16 interval; /**< How soon it can be triggered again after button. */ + + /* Constant */ + public Sint16 level; /**< Strength of the constant effect. */ + + /* Envelope */ + public Uint16 attack_length; /**< Duration of the attack. */ + public Uint16 attack_level; /**< Level at the start of the attack. */ + public Uint16 fade_length; /**< Duration of the fade. */ + public Uint16 fade_level; /**< Level at the end of the fade. */ +} + +/** + * A structure containing a template for a Periodic effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SINE + * - SDL_HAPTIC_SQUARE + * - SDL_HAPTIC_TRIANGLE + * - SDL_HAPTIC_SAWTOOTHUP + * - SDL_HAPTIC_SAWTOOTHDOWN + * + * A periodic effect consists in a wave-shaped effect that repeats itself over + * time. The type determines the shape of the wave and the parameters + * determine the dimensions of the wave. + * + * Phase is given by hundredth of a degree meaning that giving the phase a + * value of 9000 will displace it 25% of its period. Here are sample values: + * + * - 0: No phase displacement. + * - 9000: Displaced 25% of its period. + * - 18000: Displaced 50% of its period. + * - 27000: Displaced 75% of its period. + * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. + * + * Examples: + * + * ``` + * SDL_HAPTIC_SINE + * __ __ __ __ + * / \ / \ / \ / + * / \__/ \__/ \__/ + * + * SDL_HAPTIC_SQUARE + * __ __ __ __ __ + * | | | | | | | | | | + * | |__| |__| |__| |__| | + * + * SDL_HAPTIC_TRIANGLE + * /\ /\ /\ /\ /\ + * / \ / \ / \ / \ / + * / \/ \/ \/ \/ + * + * SDL_HAPTIC_SAWTOOTHUP + * /| /| /| /| /| /| /| + * / | / | / | / | / | / | / | + * / |/ |/ |/ |/ |/ |/ | + * + * SDL_HAPTIC_SAWTOOTHDOWN + * \ |\ |\ |\ |\ |\ |\ | + * \ | \ | \ | \ | \ | \ | \ | + * \| \| \| \| \| \| \| + * ``` + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_SINE + * \sa SDL_HAPTIC_SQUARE + * \sa SDL_HAPTIC_TRIANGLE + * \sa SDL_HAPTIC_SAWTOOTHUP + * \sa SDL_HAPTIC_SAWTOOTHDOWN + * \sa SDL_HapticEffect + */ +[CRepr] public struct HapticPeriodic +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN */ + public HapticDirection direction; /**< Direction of the effect. */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect. */ + public Uint16 delay; /**< Delay before starting the effect. */ + + /* Trigger */ + public Uint16 button; /**< Button that triggers the effect. */ + public Uint16 interval; /**< How soon it can be triggered again after button. */ + + /* Periodic */ + public Uint16 period; /**< Period of the wave. */ + public Sint16 magnitude; /**< Peak value; if negative, equivalent to 180 degrees extra phase shift. */ + public Sint16 offset; /**< Mean value of the wave. */ + public Uint16 phase; /**< Positive phase shift given by hundredth of a degree. */ + + /* Envelope */ + public Uint16 attack_length; /**< Duration of the attack. */ + public Uint16 attack_level; /**< Level at the start of the attack. */ + public Uint16 fade_length; /**< Duration of the fade. */ + public Uint16 fade_level; /**< Level at the end of the fade. */ +} + +/** + * A structure containing a template for a Condition effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SPRING: Effect based on axes position. + * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. + * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. + * - SDL_HAPTIC_FRICTION: Effect based on axes movement. + * + * Direction is handled by condition internals instead of a direction member. + * The condition effect specific members have three parameters. The first + * refers to the X axis, the second refers to the Y axis and the third refers + * to the Z axis. The right terms refer to the positive side of the axis and + * the left terms refer to the negative side of the axis. Please refer to the + * 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 + * \sa SDL_HAPTIC_INERTIA + * \sa SDL_HAPTIC_FRICTION + * \sa SDL_HapticEffect + */ +[CRepr] public struct HapticCondition +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ + public HapticDirection direction; /**< Direction of the effect. */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect. */ + public Uint16 delay; /**< Delay before starting the effect. */ + + /* Trigger */ + public Uint16 button; /**< Button that triggers the effect. */ + public Uint16 interval; /**< How soon it can be triggered again after button. */ + + /* Condition */ + public Uint16[3] right_sat; /**< Level when joystick is to the positive side; max 0xFFFF. */ + public Uint16[3] left_sat; /**< Level when joystick is to the negative side; max 0xFFFF. */ + public Sint16[3] right_coeff; /**< How fast to increase the force towards the positive side. */ + public Sint16[3] left_coeff; /**< How fast to increase the force towards the negative side. */ + public Uint16[3] deadband; /**< Size of the dead zone; max 0xFFFF: whole axis-range when 0-centered. */ + public Sint16[3] center; /**< Position of the dead zone. */ +} + +/** + * A structure containing a template for a Ramp effect. + * + * This struct is exclusively for the SDL_HAPTIC_RAMP effect. + * + * The ramp effect starts at start strength and ends at end strength. It + * augments in linear fashion. If you use attack and fade with a ramp the + * 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 + */ +[CRepr] public struct HapticRamp +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_RAMP */ + public HapticDirection direction; /**< Direction of the effect. */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect. */ + public Uint16 delay; /**< Delay before starting the effect. */ + + /* Trigger */ + public Uint16 button; /**< Button that triggers the effect. */ + public Uint16 interval; /**< How soon it can be triggered again after button. */ + + /* Ramp */ + public Sint16 start; /**< Beginning strength level. */ + public Sint16 end; /**< Ending strength level. */ + + /* Envelope */ + public Uint16 attack_length; /**< Duration of the attack. */ + public Uint16 attack_level; /**< Level at the start of the attack. */ + public Uint16 fade_length; /**< Duration of the fade. */ + public Uint16 fade_level; /**< Level at the end of the fade. */ +} + +/** + * A structure containing a template for a Left/Right effect. + * + * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. + * + * The Left/Right effect is used to explicitly control the large and small + * 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 + */ +[CRepr] public struct HapticLeftRight +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_LEFTRIGHT */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect in milliseconds. */ + + /* Rumble */ + public Uint16 large_magnitude; /**< Control of the large controller motor. */ + public Uint16 small_magnitude; /**< Control of the small controller motor. */ +} + +/** + * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. + * + * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. + * + * A custom force feedback effect is much like a periodic effect, where the + * application can define its exact shape. You will have to allocate the data + * yourself. Data should consist of channels * samples Uint16 samples. + * + * 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 + */ +[CRepr] public struct HapticCustom +{ + /* Header */ + public HapticEffectType type; /**< SDL_HAPTIC_CUSTOM */ + public HapticDirection direction; /**< Direction of the effect. */ + + /* Replay */ + public Uint32 length; /**< Duration of the effect. */ + public Uint16 delay; /**< Delay before starting the effect. */ + + /* Trigger */ + public Uint16 button; /**< Button that triggers the effect. */ + public Uint16 interval; /**< How soon it can be triggered again after button. */ + + /* Custom */ + public Uint8 channels; /**< Axes to use, minimum of one. */ + public Uint16 period; /**< Sample periods. */ + public Uint16 samples; /**< Amount of samples. */ + public Uint16* data; /**< Should contain channels*samples items. */ + + /* Envelope */ + public Uint16 attack_length; /**< Duration of the attack. */ + public Uint16 attack_level; /**< Level at the start of the attack. */ + public Uint16 fade_length; /**< Duration of the fade. */ + public Uint16 fade_level; /**< Level at the end of the fade. */ +} + +/** + * The generic template for any haptic effect. + * + * All values max at 32767 (0x7FFF). Signed values also can be negative. Time + * values unless specified otherwise are in milliseconds. + * + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. + * Neither delay, interval, attack_length nor fade_length support + * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. + * + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of + * SDL_HAPTIC_INFINITY. + * + * Button triggers may not be supported on all devices, it is advised to not + * use them if possible. Buttons start at index 1 instead of index 0 like the + * joystick. + * + * If both attack_length and fade_level are 0, the envelope is not used, + * otherwise both values are used. + * + * Common parts: + * + * ```c + * // Replay - All effects have this + * Uint32 length; // Duration of effect (ms). + * Uint16 delay; // Delay before starting effect. + * + * // Trigger - All effects have this + * Uint16 button; // Button that triggers effect. + * Uint16 interval; // How soon before effect can be triggered again. + * + * // Envelope - All effects except condition effects have this + * Uint16 attack_length; // Duration of the attack (ms). + * Uint16 attack_level; // Level at the start of the attack. + * Uint16 fade_length; // Duration of the fade out (ms). + * Uint16 fade_level; // Level at the end of the fade. + * ``` + * + * Here we have an example of a constant effect evolution in time: + * + * ``` + * Strength + * ^ + * | + * | effect level --> _________________ + * | / \ + * | / \ + * | / \ + * | / \ + * | attack_level --> | \ + * | | | <--- fade_level + * | + * +--------------------------------------------------> Time + * [--] [---] + * attack_length fade_length + * + * [------------------][-----------------------] + * delay length + * ``` + * + * 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 + * \sa SDL_HapticRamp + * \sa SDL_HapticLeftRight + * \sa SDL_HapticCustom + */ +[CRepr, Union] public struct HapticEffect +{ + /* Common for all force feedback effects */ + public HapticEffectType type; /**< Effect type. */ + public HapticConstant constant; /**< Constant effect. */ + public HapticPeriodic periodic; /**< Periodic effect. */ + public HapticCondition condition; /**< Condition effect. */ + public HapticRamp ramp; /**< Ramp effect. */ + public HapticLeftRight leftright; /**< Left/Right effect. */ + public HapticCustom custom; /**< Custom effect. */ +} + +/** + * 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. + */ +public typealias HapticID = Uint32; + + +/* Function prototypes */ + +/** + * Get a list of currently connected haptic devices. + * + * \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 3.2.0. + * + * \sa SDL_OpenHaptic + */ +[LinkName("SDL_GetHaptics")] public static extern HapticID* GetHaptics(out c_int count); + +/** + * Get the implementation dependent name of a haptic device. + * + * This can be called before any haptic devices are opened. + * + * \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 3.2.0. + * + * \sa SDL_GetHapticName + * \sa SDL_OpenHaptic + */ +[LinkName("SDL_GetHapticNameForID")] public static extern c_char* GetHapticNameForID(HapticID instance_id); + +/** + * Open a haptic device for use. + * + * The index passed as an argument refers to the N'th haptic device on this + * system. + * + * When opening a haptic device, its gain will be set to maximum and + * autocenter will be disabled. To modify these values use SDL_SetHapticGain() + * and SDL_SetHapticAutocenter(). + * + * \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 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_GetHaptics + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_OpenHapticFromMouse + * \sa SDL_SetHapticAutocenter + * \sa SDL_SetHapticGain + */ +[LinkName("SDL_OpenHaptic")] public static extern Haptic* OpenHaptic(HapticID instance_id); + + +/** + * Get the SDL_Haptic associated with an instance ID, if it has been opened. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetHapticFromID")] public static extern Haptic* GetHapticFromID(HapticID instance_id); + +/** + * Get the instance ID of an opened haptic device. + * + * \param haptic the SDL_Haptic device to query. + * \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 3.2.0. + */ +[LinkName("SDL_GetHapticID")] public static extern HapticID GetHapticID(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 + */ +[LinkName("SDL_GetHapticName")] public static extern c_char* GetHapticName(Haptic* haptic); + +/** + * Query whether or not the current mouse has haptic capabilities. + * + * \returns true if the mouse is haptic or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHapticFromMouse + */ +[LinkName("SDL_IsMouseHaptic")] public static extern bool IsMouseHaptic(); + +/** + * Try to open a haptic device from the current mouse. + * + * \returns the haptic device identifier or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_IsMouseHaptic + */ +[LinkName("SDL_OpenHapticFromMouse")] public static extern Haptic* OpenHapticFromMouse(); + +/** + * Query if a joystick has haptic features. + * + * \param joystick the SDL_Joystick to test for haptic capabilities. + * \returns true if the joystick is haptic or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHapticFromJoystick + */ +[LinkName("SDL_IsJoystickHaptic")] public static extern bool IsJoystickHaptic(Joystick* joystick); + +/** + * Open a haptic device for use from a joystick device. + * + * You must still close the haptic device separately. It will not be closed + * with the joystick. + * + * When opened from a joystick you should first close the haptic device before + * closing the joystick device. If not, on some implementations the haptic + * device will also get unallocated and you'll be unable to use force feedback + * on that device. + * + * \param joystick the SDL_Joystick to create a haptic device from. + * \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 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_IsJoystickHaptic + */ +[LinkName("SDL_OpenHapticFromJoystick")] public static extern Haptic* OpenHapticFromJoystick(Joystick* joystick); + +/** + * Close a haptic device previously opened with SDL_OpenHaptic(). + * + * \param haptic the SDL_Haptic device to close. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHaptic + */ +[LinkName("SDL_CloseHaptic")] public static extern void CloseHaptic(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_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 3.2.0. + * + * \sa SDL_GetMaxHapticEffectsPlaying + * \sa SDL_GetHapticFeatures + */ +[LinkName("SDL_GetMaxHapticEffects")] public static extern c_int GetMaxHapticEffects(Haptic* haptic); + +/** + * Get the number of effects a haptic device can play at the same time. + * + * This is not supported on all platforms, but will always return a value. + * + * \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 -1 on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMaxHapticEffects + * \sa SDL_GetHapticFeatures + */ +[LinkName("SDL_GetMaxHapticEffectsPlaying")] public static extern c_int GetMaxHapticEffectsPlaying(Haptic* haptic); + +/** + * Get the haptic device's supported features in bitwise manner. + * + * \param haptic the SDL_Haptic device to query. + * \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 3.2.0. + * + * \sa SDL_HapticEffectSupported + * \sa SDL_GetMaxHapticEffects + */ +[LinkName("SDL_GetHapticFeatures")] public static extern Uint32 GetHapticFeatures(Haptic* haptic); + +/** + * Get the number of haptic axes the device has. + * + * The number of haptic axes might be useful if working with the + * SDL_HapticDirection effect. + * + * \param haptic the SDL_Haptic device to query. + * \returns the number of axes on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetNumHapticAxes")] public static extern c_int GetNumHapticAxes(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 true if the effect is supported or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateHapticEffect + * \sa SDL_GetHapticFeatures + */ +[LinkName("SDL_HapticEffectSupported")] public static extern bool HapticEffectSupported(Haptic* haptic, HapticEffect* effect); + +/** + * Create a new haptic effect on a specified device. + * + * \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 -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyHapticEffect + * \sa SDL_RunHapticEffect + * \sa SDL_UpdateHapticEffect + */ +[LinkName("SDL_CreateHapticEffect")] public static extern HapticEffectID CreateHapticEffect(Haptic* haptic, HapticEffect* effect); + +/** + * Update the properties of an effect. + * + * 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_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 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_CreateHapticEffect + * \sa SDL_RunHapticEffect + */ +[LinkName("SDL_UpdateHapticEffect")] public static extern bool UpdateHapticEffect(Haptic* haptic, HapticEffectID effect, HapticEffect* data); + +/** + * Run the haptic effect on its associated haptic device. + * + * To repeat the effect over and over indefinitely, set `iterations` to + * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make + * one instance of the effect last indefinitely (so the effect does not fade), + * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` + * instead. + * + * \param haptic the SDL_Haptic device to run the effect on. + * \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 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_GetHapticEffectStatus + * \sa SDL_StopHapticEffect + * \sa SDL_StopHapticEffects + */ +[LinkName("SDL_RunHapticEffect")] public static extern bool RunHapticEffect(Haptic* haptic, 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 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_RunHapticEffect + * \sa SDL_StopHapticEffects + */ +[LinkName("SDL_StopHapticEffect")] public static extern bool StopHapticEffect(Haptic* haptic, HapticEffectID effect); + +/** + * Destroy a haptic effect on the device. + * + * This will stop the effect if it's running. Effects are automatically + * destroyed when the device is closed. + * + * \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 3.2.0. + * + * \sa SDL_CreateHapticEffect + */ +[LinkName("SDL_DestroyHapticEffect")] public static extern void DestroyHapticEffect(Haptic* haptic, HapticEffectID effect); + +/** + * Get the status of the current effect on the specified haptic device. + * + * Device must support the SDL_HAPTIC_STATUS feature. + * + * \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 true if it is playing, false if it isn't playing or haptic status + * isn't supported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticFeatures + */ +[LinkName("SDL_GetHapticEffectStatus")] public static extern bool GetHapticEffectStatus(Haptic* haptic, HapticEffectID effect); + +/** + * Set the global gain of the specified haptic device. + * + * Device must support the SDL_HAPTIC_GAIN feature. + * + * 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_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 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_GetHapticFeatures + */ +[LinkName("SDL_SetHapticGain")] public static extern bool SetHapticGain(Haptic* haptic, c_int gain); + +/** + * Set the global autocenter of the device. + * + * Autocenter should be between 0 and 100. Setting it to 0 will disable + * autocentering. + * + * Device must support the SDL_HAPTIC_AUTOCENTER feature. + * + * \param haptic the SDL_Haptic device to set autocentering on. + * \param autocenter value to set autocenter to (0-100). + * \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_GetHapticFeatures + */ +[LinkName("SDL_SetHapticAutocenter")] public static extern bool SetHapticAutocenter(Haptic* haptic, c_int autocenter); + +/** + * Pause a haptic device. + * + * 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 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_ResumeHaptic + */ +[LinkName("SDL_PauseHaptic")] public static extern bool PauseHaptic(Haptic* haptic); + +/** + * Resume a haptic device. + * + * Call to unpause after SDL_PauseHaptic(). + * + * \param haptic the SDL_Haptic device to unpause. + * \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_PauseHaptic + */ +[LinkName("SDL_ResumeHaptic")] public static extern bool ResumeHaptic(Haptic* haptic); + +/** + * Stop all the currently playing effects on a haptic device. + * + * \param haptic the SDL_Haptic device to stop. + * \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_RunHapticEffect + * \sa SDL_StopHapticEffects + */ +[LinkName("SDL_StopHapticEffects")] public static extern bool StopHapticEffects(Haptic* haptic); + +/** + * Check whether rumble is supported on a haptic device. + * + * \param haptic haptic device to check for rumble support. + * \returns true if the effect is supported or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InitHapticRumble + */ +[LinkName("SDL_HapticRumbleSupported")] public static extern bool HapticRumbleSupported(Haptic* haptic); + +/** + * Initialize a haptic device for simple rumble playback. + * + * \param haptic the haptic device to initialize for simple rumble playback. + * \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_PlayHapticRumble + * \sa SDL_StopHapticRumble + * \sa SDL_HapticRumbleSupported + */ +[LinkName("SDL_InitHapticRumble")] public static extern bool InitHapticRumble(Haptic* haptic); + +/** + * Run a simple rumble effect on a haptic device. + * + * \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 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_InitHapticRumble + * \sa SDL_StopHapticRumble + */ +[LinkName("SDL_PlayHapticRumble")] public static extern bool PlayHapticRumble(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 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_PlayHapticRumble + */ +[LinkName("SDL_StopHapticRumble")] public static extern bool StopHapticRumble(Haptic* haptic); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_haptic_h_ */ \ No newline at end of file diff --git a/src/SDL_hidapi.bf b/src/SDL_hidapi.bf new file mode 100644 index 0000000..7dc37f2 --- /dev/null +++ b/src/SDL_hidapi.bf @@ -0,0 +1,582 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * An opaque handle representing an open HID device. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct hid_device; + +/** + * HID underlying bus types. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum hid_bus_type : c_int { + /** Unknown bus type */ + ApiBusUnknown = 0x00, + + /** USB bus + Specifications: + https://usb.org/hid */ + ApiBusUsb = 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/ */ + ApiBusBluetooth = 0x02, + + /** I2C bus + Specifications: + https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */ + ApiBusI2c = 0x03, + + /** SPI bus + Specifications: + https://www.microsoft.com/download/details.aspx?id=103325 */ + ApiBusSpi = 0x04, + +} + +/** hidapi info structure */ + +/** + * Information about a connected HID device + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct hid_device_info +{ + /** Platform-specific device path */ + public c_char* path; + /** Device Vendor ID */ + public c_ushort vendor_id; + /** Device Product ID */ + public c_ushort product_id; + /** Serial Number */ + public c_wchar* serial_number; + /** Device Release Number in binary-coded decimal, + also known as Device Version Number */ + public c_ushort release_number; + /** Manufacturer String */ + public c_wchar* manufacturer_string; + /** Product string */ + public c_wchar* product_string; + /** Usage Page for this Device/Interface + (Windows/Mac/hidraw only) */ + public c_ushort usage_page; + /** Usage for this Device/Interface + (Windows/Mac/hidraw only) */ + public c_ushort 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. + */ + public c_int interface_number; + + /** Additional information about the USB interface. + Valid on libusb and Android implementations. */ + public c_int interface_class; + public c_int interface_subclass; + public c_int interface_protocol; + + /** Underlying bus type */ + public hid_bus_type bus_type; + + /** Pointer to the next device */ + public hid_device_info* next; + +} + + +/** + * 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(), + * SDL_hid_open(), and SDL_hid_open_path() if 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 + */ +[LinkName("SDL_hid_init")] public static extern c_int hid_init(); + +/** + * 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 + */ +[LinkName("SDL_hid_exit")] public static extern c_int hid_exit(); + +/** + * 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 + */ +[LinkName("SDL_hid_device_change_count")] public static extern Uint32 hid_device_change_count(); + +/** + * 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 + */ +[LinkName("SDL_hid_enumerate")] public static extern hid_device_info* hid_enumerate(c_ushort vendor_id, c_ushort 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. + */ +[LinkName("SDL_hid_free_enumeration")] public static extern void hid_free_enumeration(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. + */ +[LinkName("SDL_hid_open")] public static extern hid_device* hid_open(c_ushort vendor_id, c_ushort product_id, c_wchar* 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. + */ +[LinkName("SDL_hid_open_path")] public static extern hid_device* hid_open_path(c_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. + */ +[LinkName("SDL_hid_get_properties")] public static extern PropertiesID hid_get_properties(hid_device* dev); + +public const let 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. + */ +[LinkName("SDL_hid_write")] public static extern c_int hid_write(hid_device* dev, c_uchar* data, c_size 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. + */ +[LinkName("SDL_hid_read_timeout")] public static extern c_int hid_read_timeout(hid_device* dev, c_uchar* data, c_size length, c_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. + */ +[LinkName("SDL_hid_read")] public static extern c_int hid_read(hid_device* dev, c_uchar* data, c_size 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. + */ +[LinkName("SDL_hid_set_nonblocking")] public static extern c_int hid_set_nonblocking(hid_device* dev, c_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. + */ +[LinkName("SDL_hid_send_feature_report")] public static extern c_int hid_send_feature_report(hid_device* dev, c_uchar* data, c_size 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. + */ +[LinkName("SDL_hid_get_feature_report")] public static extern c_int hid_get_feature_report(hid_device* dev, c_uchar* data, c_size 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. + */ +[LinkName("SDL_hid_get_input_report")] public static extern c_int hid_get_input_report(hid_device* dev, c_uchar* data, c_size 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. + */ +[LinkName("SDL_hid_close")] public static extern c_int hid_close(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. + */ +[LinkName("SDL_hid_get_manufacturer_string")] public static extern c_int hid_get_manufacturer_string(hid_device* dev, c_wchar* string, c_size 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. + */ +[LinkName("SDL_hid_get_product_string")] public static extern c_int hid_get_product_string(hid_device* dev, c_wchar* string, c_size 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. + */ +[LinkName("SDL_hid_get_serial_number_string")] public static extern c_int hid_get_serial_number_string(hid_device* dev, c_wchar* string, c_size 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. + */ +[LinkName("SDL_hid_get_indexed_string")] public static extern c_int hid_get_indexed_string(hid_device* dev, c_int string_index, c_wchar* string, c_size 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. + */ +[LinkName("SDL_hid_get_device_info")] public static extern hid_device_info* hid_get_device_info(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. + */ +[LinkName("SDL_hid_get_report_descriptor")] public static extern c_int hid_get_report_descriptor(hid_device* dev, c_uchar* buf, c_size 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. + */ +[LinkName("SDL_hid_ble_scan")] public static extern void hid_ble_scan(bool active); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_hidapi_h_ */ \ No newline at end of file diff --git a/src/SDL_hints.bf b/src/SDL_hints.bf new file mode 100644 index 0000000..f112cf5 --- /dev/null +++ b/src/SDL_hints.bf @@ -0,0 +1,4898 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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 + */ +public const let 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 + */ +public const let 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 + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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 + * + * 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_ENABLE_SCREEN_KEYBOARD = "SDL_ENABLE_SCREEN_KEYBOARD"; + +/** + * A variable containing a list of evdev devices to use if udev is not + * available. + * + * The list of devices is in the form: + * + * deviceclass:path[,deviceclass:path[,...]] + * + * where device class is an integer representing the SDL_UDEV_deviceclass and + * path is the full path to the event device. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_GPU_DRIVER = "SDL_GPU_DRIVER"; + +/** + * A variable that specifies the library name to use when loading the OpenXR + * loader. + * + * By default, SDL will try the system default name, but on some platforms + * like Windows, debug builds of the OpenXR loader have a different name, and + * are not always directly compatible with release applications. Setting this + * hint allows you to compensate for this difference in your app when + * applicable. + * + * This hint should be set before the OpenXR loader is loaded. For example, + * creating an OpenXR GPU device will load the OpenXR loader. + */ +public const let HINT_OPENXR_LIBRARY = "SDL_OPENXR_LIBRARY"; + +/** + * 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_JOYSTICK_GAMEINPUT = "SDL_JOYSTICK_GAMEINPUT"; + +/** + * A variable containing a list of devices known to have a GameCube form + * factor. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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 and Wayland. + * + * This hint needs to be set before creating cursors. + * + * \since This hint is available since SDL 3.4.0. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_OPENGL_ES_DRIVER = "SDL_OPENGL_ES_DRIVER"; + +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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 + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_VIDEO_WIN_D3DCOMPILER = "SDL_VIDEO_WIN_D3DCOMPILER"; + +/** + * A variable controlling whether SDL should call XSelectInput() to enable + * input events on X11 windows wrapped by SDL windows. + * + * The variable can be set to the following values: + * + * - "0": Don't call XSelectInput(), assuming the native window code has done + * it already. + * - "1": Call XSelectInput() to enable input events. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.10. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_WINDOWS_RAW_KEYBOARD_EXCLUDE_HOTKEYS = "SDL_WINDOWS_RAW_KEYBOARD_EXCLUDE_HOTKEYS"; + +/** + * 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let 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. + */ +public const let HINT_PEN_TOUCH_EVENTS = "SDL_PEN_TOUCH_EVENTS"; + +/** + * An enumeration of hint priorities. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum HintPriority : c_int +{ + Default, + Normal, + Override, +} + +/** + * 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 + */ +[LinkName("SDL_SetHintWithPriority")] public static extern bool SetHintWithPriority(c_char* name, c_char* value, 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 + */ +[LinkName("SDL_SetHint")] public static extern bool SetHint(c_char* name, c_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 + */ +[LinkName("SDL_ResetHint")] public static extern bool ResetHint(c_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 + */ +[LinkName("SDL_ResetHints")] public static extern void ResetHints(); + +/** + * 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 + */ +[LinkName("SDL_GetHint")] public static extern c_char* GetHint(c_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 + */ +[LinkName("SDL_GetHintBoolean")] public static extern bool GetHintBoolean(c_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 + */ +public function void HintCallback(void* userdata, c_char* name, c_char* oldValue, c_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 + */ +[LinkName("SDL_AddHintCallback")] public static extern bool AddHintCallback(c_char* name, 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 + */ +[LinkName("SDL_RemoveHintCallback")] public static extern void RemoveHintCallback(c_char* name, HintCallback callback, void* userdata); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_hints_h_ */ \ No newline at end of file diff --git a/src/SDL_init.bf b/src/SDL_init.bf new file mode 100644 index 0000000..7715d5b --- /dev/null +++ b/src/SDL_init.bf @@ -0,0 +1,509 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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(). + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* 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 + */ +public enum InitFlags : Uint32 +{ + Audio = 0x00000010u, /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ + Video = 0x00000020u, /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ + Joystick = 0x00000200u, /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS` */ + Haptic = 0x00001000u, + Gamepad = 0x00002000u, /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ + Events = 0x00004000u, + Sensor = 0x00008000u, /**< `SDL_INIT_SENSOR` implies `SDL_INIT_EVENTS` */ + Camera = 0x00010000u, /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */ +} /**< `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. + */ +[AllowDuplicates] public enum AppResult : c_int +{ + Continue, /**< Value that requests that the app continue from the main callbacks. */ + Success, /**< Value that requests termination with success from the main callbacks. */ + Failure, /**< Value that requests termination with error from the main callbacks. */ +} + +/** + * 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. + */ +public function AppResult AppInit_func(void** appstate, c_int argc, c_char**); + +/** + * 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. + */ +public function AppResult 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. + */ +public function AppResult AppEvent_func(void* appstate, 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. + */ +public function void AppQuit_func(void* appstate, AppResult result); + + +/** + * Initialize the SDL library. + * + * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the + * two may be used interchangeably. Though for readability of your code + * SDL_InitSubSystem() might be preferred. + * + * The file I/O (for example: SDL_IOFromFile) and threading (SDL_CreateThread) + * subsystems are initialized by default. Message boxes + * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the + * video subsystem, in hopes of being useful in showing an error dialog when + * SDL_Init fails. You must specifically initialize other subsystems if you + * use them in your application. + * + * Logging (such as SDL_Log) works without initialization, too. + * + * `flags` may be any of the following OR'd together: + * + * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events + * subsystem + * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events + * subsystem, should be initialized on the main thread. + * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the + * events subsystem + * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem + * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically initializes the + * joystick subsystem + * - `SDL_INIT_EVENTS`: events subsystem + * - `SDL_INIT_SENSOR`: sensor subsystem; automatically initializes the events + * subsystem + * - `SDL_INIT_CAMERA`: camera subsystem; automatically initializes the events + * subsystem + * + * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem() + * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or + * call SDL_Quit() to force shutdown). If a subsystem is already loaded then + * this call will increase the ref-count and return. + * + * Consider reporting some basic metadata about your application before + * calling SDL_Init, using either SDL_SetAppMetadata() or + * SDL_SetAppMetadataProperty(). + * + * \param flags subsystem initialization flags. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAppMetadata + * \sa SDL_SetAppMetadataProperty + * \sa SDL_InitSubSystem + * \sa SDL_Quit + * \sa SDL_SetMainReady + * \sa SDL_WasInit + */ +[LinkName("SDL_Init")] public static extern bool Init(InitFlags flags); + +/** + * Compatibility function to initialize the SDL library. + * + * This function and SDL_Init() are interchangeable. + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_Quit + * \sa SDL_QuitSubSystem + */ +[LinkName("SDL_InitSubSystem")] public static extern bool InitSubSystem(InitFlags flags); + +/** + * Shut down specific SDL subsystems. + * + * You still need to call SDL_Quit() even if you close all open subsystems + * with SDL_QuitSubSystem(). + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InitSubSystem + * \sa SDL_Quit + */ +[LinkName("SDL_QuitSubSystem")] public static extern void QuitSubSystem(InitFlags flags); + +/** + * Get a mask of the specified subsystems which are currently initialized. + * + * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. + * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it + * returns the initialization status of the specified subsystems. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_InitSubSystem + */ +[LinkName("SDL_WasInit")] public static extern InitFlags WasInit(InitFlags flags); + +/** + * Clean up all initialized subsystems. + * + * You should call this function even if you have already shutdown each + * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this + * function even in the case of errors in initialization. + * + * You can use this function with atexit() to ensure that it is run when your + * application is shutdown, but it is not wise to do this from a library or + * other dynamically loaded code. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + * \sa SDL_QuitSubSystem + */ +[LinkName("SDL_Quit")] public static extern void Quit(); + +/** + * 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 + */ +[LinkName("SDL_IsMainThread")] public static extern bool IsMainThread(); + +/** + * 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 + */ +public function void 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 + */ +[LinkName("SDL_RunOnMainThread")] public static extern bool RunOnMainThread(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 + */ +[LinkName("SDL_SetAppMetadata")] public static extern bool SetAppMetadata(c_char* appname, c_char* appversion, c_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 + */ +[LinkName("SDL_SetAppMetadataProperty")] public static extern bool SetAppMetadataProperty(c_char* name, c_char* value); + +public const let PROP_APP_METADATA_NAME_STRING = "SDL.app.metadata.name"; +public const let PROP_APP_METADATA_VERSION_STRING = "SDL.app.metadata.version"; +public const let PROP_APP_METADATA_IDENTIFIER_STRING = "SDL.app.metadata.identifier"; +public const let PROP_APP_METADATA_CREATOR_STRING = "SDL.app.metadata.creator"; +public const let PROP_APP_METADATA_COPYRIGHT_STRING = "SDL.app.metadata.copyright"; +public const let PROP_APP_METADATA_URL_STRING = "SDL.app.metadata.url"; +public const let 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 + */ +[LinkName("SDL_GetAppMetadataProperty")] public static extern c_char* GetAppMetadataProperty(c_char* name); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_init_h_ */ \ No newline at end of file diff --git a/src/SDL_iostream.bf b/src/SDL_iostream.bf new file mode 100644 index 0000000..5450eb6 --- /dev/null +++ b/src/SDL_iostream.bf @@ -0,0 +1,1390 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * SDL_IOStream status, set by a read or write operation. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum IOStatus : c_int +{ + Ready, /**< Everything is ready (no errors and not EOF). */ + Error, /**< Read or write I/O error */ + Eof, /**< End of file */ + NotReady, /**< Non blocking I/O, not ready */ + Readonly, /**< Tried to write a read-only buffer */ + Writeonly, /**< Tried to read a write-only buffer */ +} + +/** + * 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. + */ +[AllowDuplicates] public enum IOWhence : c_int +{ + SeekSet, /**< Seek from the beginning of data */ + SeekCur, /**< Seek relative to current read point */ + SeekEnd, /**< Seek relative to the end of data */ +} + +/** + * 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 + */ +[CRepr] public struct IOStreamInterface +{ + /* The version of this interface */ + public Uint32 version; + + /** + * Return the number of bytes in this SDL_IOStream + * + * \return the total size of the data stream, or -1 on error. + */ + public function Sint64(void* userdata) size; + + /** + * 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. + */ + public function Sint64(void* userdata, Sint64 offset, IOWhence whence) seek; + + /** + * 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 + */ + public function c_size(void* userdata, void* ptr, c_size size, IOStatus* status) read; + + /** + * 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 + */ + public function c_size(void* userdata, void* ptr, c_size size, IOStatus* status) write; + + /** + * 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. + */ + public function bool(void*, IOStatus*) flush; + + /** + * 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. + */ + public function bool(void*) close; + +} + +/* 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. + */ + + + + +/** + * 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. + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_IOFromFile")] public static extern IOStream* IOFromFile(c_char* file, c_char* mode); + +public const let PROP_IOSTREAM_WINDOWS_HANDLE_POINTER = "SDL.iostream.windows.handle"; +public const let PROP_IOSTREAM_STDIO_FILE_POINTER = "SDL.iostream.stdio.file"; +public const let PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER = "SDL.iostream.file_descriptor"; +public const let 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 + */ +[LinkName("SDL_IOFromMem")] public static extern IOStream* IOFromMem(void* mem, c_size size); + +public const let PROP_IOSTREAM_MEMORY_POINTER = "SDL.iostream.memory.base"; +public const let PROP_IOSTREAM_MEMORY_SIZE_NUMBER = "SDL.iostream.memory.size"; +public const let 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 + */ +[LinkName("SDL_IOFromConstMem")] public static extern IOStream* IOFromConstMem(void* mem, c_size 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 + */ +[LinkName("SDL_IOFromDynamicMem")] public static extern IOStream* IOFromDynamicMem(); + +public const let PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER = "SDL.iostream.dynamic.memory"; +public const let 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 + */ +[LinkName("SDL_OpenIO")] public static extern IOStream* OpenIO(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 + */ +[LinkName("SDL_CloseIO")] public static extern bool CloseIO(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. + */ +[LinkName("SDL_GetIOProperties")] public static extern PropertiesID GetIOProperties(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. + */ +[LinkName("SDL_GetIOStatus")] public static extern IOStatus GetIOStatus(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. + */ +[LinkName("SDL_GetIOSize")] public static extern Sint64 GetIOSize(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 + */ +[LinkName("SDL_SeekIO")] public static extern Sint64 SeekIO(IOStream* context, Sint64 offset, 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 + */ +[LinkName("SDL_TellIO")] public static extern Sint64 TellIO(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 + */ +[LinkName("SDL_ReadIO")] public static extern c_size ReadIO(IOStream* context, void* ptr, c_size 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 + */ +[LinkName("SDL_WriteIO")] public static extern c_size WriteIO(IOStream* context, void* ptr, c_size 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 + */ +[LinkName("SDL_IOprintf")] public static extern c_size IOprintf(IOStream* context, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_IOvprintf")] public static extern c_size IOvprintf(IOStream* context, c_char* fmt, VarArgs ap); + +/** + * 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 + */ +[LinkName("SDL_FlushIO")] public static extern bool FlushIO(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 + */ +[LinkName("SDL_LoadFile_IO")] public static extern void* LoadFile_IO(IOStream* src, out c_size 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 + */ +[LinkName("SDL_LoadFile")] public static extern void* LoadFile(c_char* file, c_size* 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 + */ +[LinkName("SDL_SaveFile_IO")] public static extern bool SaveFile_IO(IOStream* src, void* data, c_size 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 + */ +[LinkName("SDL_SaveFile")] public static extern bool SaveFile(c_char* file, void* data, c_size 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. + */ +[LinkName("SDL_ReadU8")] public static extern bool ReadU8(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS8")] public static extern bool ReadS8(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU16LE")] public static extern bool ReadU16LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS16LE")] public static extern bool ReadS16LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU16BE")] public static extern bool ReadU16BE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS16BE")] public static extern bool ReadS16BE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU32LE")] public static extern bool ReadU32LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS32LE")] public static extern bool ReadS32LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU32BE")] public static extern bool ReadU32BE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS32BE")] public static extern bool ReadS32BE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU64LE")] public static extern bool ReadU64LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS64LE")] public static extern bool ReadS64LE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadU64BE")] public static extern bool ReadU64BE(IOStream* src, out 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. + */ +[LinkName("SDL_ReadS64BE")] public static extern bool ReadS64BE(IOStream* src, out 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. + */ +[LinkName("SDL_WriteU8")] public static extern bool WriteU8(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. + */ +[LinkName("SDL_WriteS8")] public static extern bool WriteS8(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. + */ +[LinkName("SDL_WriteU16LE")] public static extern bool WriteU16LE(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. + */ +[LinkName("SDL_WriteS16LE")] public static extern bool WriteS16LE(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. + */ +[LinkName("SDL_WriteU16BE")] public static extern bool WriteU16BE(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. + */ +[LinkName("SDL_WriteS16BE")] public static extern bool WriteS16BE(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. + */ +[LinkName("SDL_WriteU32LE")] public static extern bool WriteU32LE(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. + */ +[LinkName("SDL_WriteS32LE")] public static extern bool WriteS32LE(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. + */ +[LinkName("SDL_WriteU32BE")] public static extern bool WriteU32BE(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. + */ +[LinkName("SDL_WriteS32BE")] public static extern bool WriteS32BE(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. + */ +[LinkName("SDL_WriteU64LE")] public static extern bool WriteU64LE(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. + */ +[LinkName("SDL_WriteS64LE")] public static extern bool WriteS64LE(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. + */ +[LinkName("SDL_WriteU64BE")] public static extern bool WriteU64BE(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. + */ +[LinkName("SDL_WriteS64BE")] public static extern bool WriteS64BE(IOStream* dst, Sint64 value); +} + +/* @} */ /* Write endian functions */ + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_iostream_h_ */ \ No newline at end of file diff --git a/src/SDL_joystick.bf b/src/SDL_joystick.bf new file mode 100644 index 0000000..b78bc12 --- /dev/null +++ b/src/SDL_joystick.bf @@ -0,0 +1,1411 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + + +/* + * 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! + */ + + + +/** + * The joystick structure used to identify an SDL joystick. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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. + */ +public typealias JoystickID = Uint32; + +/** + * 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. + */ +[AllowDuplicates] public enum JoystickType : c_int +{ + Unknown, + Gamepad, + Wheel, + ArcadeStick, + FlightStick, + DancePad, + Guitar, + DrumKit, + ArcadePad, + Throttle, + Count, +} + +/** + * 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. + */ +[AllowDuplicates] public enum JoystickConnectionState : c_int +{ + Invalid = -1, + Unknown, + Wired, + Wireless, +} + +/** + * 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 + */ +public const let 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 + */ +public const let 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. + */ +[LinkName("SDL_LockJoysticks")] public static extern void LockJoysticks(); + +/** + * 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. + * + * \returns true if the joysticks were successfully locked, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.6.0. + */ +[LinkName("SDL_TryLockJoysticks")] public static extern bool TryLockJoysticks(); + +/** + * 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. + */ +[LinkName("SDL_UnlockJoysticks")] public static extern void UnlockJoysticks(); + +/** + * 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 + */ +[LinkName("SDL_HasJoystick")] public static extern bool HasJoystick(); + +/** + * 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 + */ +[LinkName("SDL_GetJoysticks")] public static extern JoystickID* GetJoysticks(out c_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 + */ +[LinkName("SDL_GetJoystickNameForID")] public static extern c_char* GetJoystickNameForID(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 + */ +[LinkName("SDL_GetJoystickPathForID")] public static extern c_char* GetJoystickPathForID(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 + */ +[LinkName("SDL_GetJoystickPlayerIndexForID")] public static extern c_int GetJoystickPlayerIndexForID(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 + */ +[LinkName("SDL_GetJoystickGUIDForID")] public static extern GUID GetJoystickGUIDForID(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 + */ +[LinkName("SDL_GetJoystickVendorForID")] public static extern Uint16 GetJoystickVendorForID(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 + */ +[LinkName("SDL_GetJoystickProductForID")] public static extern Uint16 GetJoystickProductForID(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 + */ +[LinkName("SDL_GetJoystickProductVersionForID")] public static extern Uint16 GetJoystickProductVersionForID(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 + */ +[LinkName("SDL_GetJoystickTypeForID")] public static extern JoystickType GetJoystickTypeForID(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 + */ +[LinkName("SDL_OpenJoystick")] public static extern Joystick* OpenJoystick(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. + */ +[LinkName("SDL_GetJoystickFromID")] public static extern Joystick* GetJoystickFromID(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 + */ +[LinkName("SDL_GetJoystickFromPlayerIndex")] public static extern Joystick* GetJoystickFromPlayerIndex(c_int player_index); + +/** + * The structure that describes a virtual joystick touchpad. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_VirtualJoystickDesc + */ +[CRepr] public struct VirtualJoystickTouchpadDesc +{ + public Uint16 nfingers; /**< the number of simultaneous fingers on this touchpad */ + public Uint16[3] padding; +} + +/** + * The structure that describes a virtual joystick sensor. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_VirtualJoystickDesc + */ +[CRepr] public struct VirtualJoystickSensorDesc +{ + public SensorType type; /**< the type of this sensor */ + public float rate; /**< the update frequency of this sensor, may be 0.0f */ +} + +/** + * 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 + */ +[CRepr] public struct VirtualJoystickDesc +{ + public Uint32 version; /**< the version of this interface */ + public Uint16 type; /**< `SDL_JoystickType` */ + public Uint16 padding; /**< unused */ + public Uint16 vendor_id; /**< the USB vendor ID of this joystick */ + public Uint16 product_id; /**< the USB product ID of this joystick */ + public Uint16 naxes; /**< the number of axes on this joystick */ + public Uint16 nbuttons; /**< the number of buttons on this joystick */ + public Uint16 nballs; /**< the number of balls on this joystick */ + public Uint16 nhats; /**< the number of hats on this joystick */ + public Uint16 ntouchpads; /**< the number of touchpads on this joystick, requires `touchpads` to point at valid descriptions */ + public Uint16 nsensors; /**< the number of sensors on this joystick, requires `sensors` to point at valid descriptions */ + public Uint16[2] padding2; /**< unused */ + public Uint32 button_mask; /**< A mask of which buttons are valid for this controller + e.g. (1 << SDL_GAMEPAD_BUTTON_SOUTH) */ + public Uint32 axis_mask; /**< A mask of which axes are valid for this controller + e.g. (1 << SDL_GAMEPAD_AXIS_LEFTX) */ + public c_char* name; /**< the name of the joystick */ + public VirtualJoystickTouchpadDesc* touchpads; /**< A pointer to an array of touchpad descriptions, required if `ntouchpads` is > 0 */ + public VirtualJoystickSensorDesc* sensors; /**< A pointer to an array of sensor descriptions, required if `nsensors` is > 0 */ + + public void* userdata; /**< User data pointer passed to callbacks */ + public function void(void* userdata) Update; /**< Called when the joystick state should be updated */ + public function void(void* userdata, c_int player_index) SetPlayerIndex; /**< Called when the player index is set */ + public function bool(void*, Uint16, Uint16) Rumble; /**< Implements SDL_RumbleJoystick() */ + public function bool(void*, Uint16, Uint16) RumbleTriggers; /**< Implements SDL_RumbleJoystickTriggers() */ + public function bool(void*, Uint8, Uint8, Uint8) SetLED; /**< Implements SDL_SetJoystickLED() */ + public function bool(void*, void*, c_int) SendEffect; /**< Implements SDL_SendJoystickEffect() */ + public function bool(void*, bool) SetSensorsEnabled; /**< Implements SDL_SetGamepadSensorEnabled() */ + public function void(void* userdata) Cleanup; /**< Cleans up the userdata when the joystick is detached */ +} + +/* 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. + */ + + + + +/** + * 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 + */ +[LinkName("SDL_AttachVirtualJoystick")] public static extern JoystickID AttachVirtualJoystick(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 + */ +[LinkName("SDL_DetachVirtualJoystick")] public static extern bool DetachVirtualJoystick(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. + */ +[LinkName("SDL_IsJoystickVirtual")] public static extern bool IsJoystickVirtual(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 + */ +[LinkName("SDL_SetJoystickVirtualAxis")] public static extern bool SetJoystickVirtualAxis(Joystick* joystick, c_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 + */ +[LinkName("SDL_SetJoystickVirtualBall")] public static extern bool SetJoystickVirtualBall(Joystick* joystick, c_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 + */ +[LinkName("SDL_SetJoystickVirtualButton")] public static extern bool SetJoystickVirtualButton(Joystick* joystick, c_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 + */ +[LinkName("SDL_SetJoystickVirtualHat")] public static extern bool SetJoystickVirtualHat(Joystick* joystick, c_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 + */ +[LinkName("SDL_SetJoystickVirtualTouchpad")] public static extern bool SetJoystickVirtualTouchpad(Joystick* joystick, c_int touchpad, c_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 + */ +[LinkName("SDL_SendJoystickVirtualSensorData")] public static extern bool SendJoystickVirtualSensorData(Joystick* joystick, SensorType type, Uint64 sensor_timestamp, float* data, c_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. + */ +[LinkName("SDL_GetJoystickProperties")] public static extern PropertiesID GetJoystickProperties(Joystick* joystick); + +public const let PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN = "SDL.joystick.cap.mono_led"; +public const let PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN = "SDL.joystick.cap.rgb_led"; +public const let PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN = "SDL.joystick.cap.player_led"; +public const let PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN = "SDL.joystick.cap.rumble"; +public const let 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 + */ +[LinkName("SDL_GetJoystickName")] public static extern c_char* GetJoystickName(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 + */ +[LinkName("SDL_GetJoystickPath")] public static extern c_char* GetJoystickPath(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 + */ +[LinkName("SDL_GetJoystickPlayerIndex")] public static extern c_int GetJoystickPlayerIndex(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 + */ +[LinkName("SDL_SetJoystickPlayerIndex")] public static extern bool SetJoystickPlayerIndex(Joystick* joystick, c_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 + */ +[LinkName("SDL_GetJoystickGUID")] public static extern GUID GetJoystickGUID(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 + */ +[LinkName("SDL_GetJoystickVendor")] public static extern Uint16 GetJoystickVendor(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 + */ +[LinkName("SDL_GetJoystickProduct")] public static extern Uint16 GetJoystickProduct(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 + */ +[LinkName("SDL_GetJoystickProductVersion")] public static extern Uint16 GetJoystickProductVersion(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. + */ +[LinkName("SDL_GetJoystickFirmwareVersion")] public static extern Uint16 GetJoystickFirmwareVersion(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. + */ +[LinkName("SDL_GetJoystickSerial")] public static extern c_char* GetJoystickSerial(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 + */ +[LinkName("SDL_GetJoystickType")] public static extern JoystickType GetJoystickType(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 + */ +[LinkName("SDL_GetJoystickGUIDInfo")] public static extern void GetJoystickGUIDInfo(GUID guid, out Uint16 vendor, out Uint16 product, out Uint16 version, out 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. + */ +[LinkName("SDL_JoystickConnected")] public static extern bool JoystickConnected(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. + */ +[LinkName("SDL_GetJoystickID")] public static extern JoystickID GetJoystickID(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 + */ +[LinkName("SDL_GetNumJoystickAxes")] public static extern c_int GetNumJoystickAxes(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 + */ +[LinkName("SDL_GetNumJoystickBalls")] public static extern c_int GetNumJoystickBalls(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 + */ +[LinkName("SDL_GetNumJoystickHats")] public static extern c_int GetNumJoystickHats(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 + */ +[LinkName("SDL_GetNumJoystickButtons")] public static extern c_int GetNumJoystickButtons(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 + */ +[LinkName("SDL_SetJoystickEventsEnabled")] public static extern void 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 + */ +[LinkName("SDL_JoystickEventsEnabled")] public static extern bool JoystickEventsEnabled(); + +/** + * 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. + */ +[LinkName("SDL_UpdateJoysticks")] public static extern void UpdateJoysticks(); + +/** + * 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 + */ +[LinkName("SDL_GetJoystickAxis")] public static extern Sint16 GetJoystickAxis(Joystick* joystick, c_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. + */ +[LinkName("SDL_GetJoystickAxisInitialState")] public static extern bool GetJoystickAxisInitialState(Joystick* joystick, c_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 + */ +[LinkName("SDL_GetJoystickBall")] public static extern bool GetJoystickBall(Joystick* joystick, c_int ball, c_int* dx, c_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 + */ +[LinkName("SDL_GetJoystickHat")] public static extern Uint8 GetJoystickHat(Joystick* joystick, c_int hat); + +public const let HAT_CENTERED = 0x00u; +public const let HAT_UP = 0x01u; +public const let HAT_RIGHT = 0x02u; +public const let HAT_DOWN = 0x04u; +public const let HAT_LEFT = 0x08u; +public const let HAT_RIGHTUP = (HAT_RIGHT|HAT_UP); +public const let HAT_RIGHTDOWN = (HAT_RIGHT|HAT_DOWN); +public const let HAT_LEFTUP = (HAT_LEFT|HAT_UP); +public const let HAT_LEFTDOWN = (HAT_LEFT|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 + */ +[LinkName("SDL_GetJoystickButton")] public static extern bool GetJoystickButton(Joystick* joystick, c_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. + */ +[LinkName("SDL_RumbleJoystick")] public static extern bool RumbleJoystick(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 + */ +[LinkName("SDL_RumbleJoystickTriggers")] public static extern bool RumbleJoystickTriggers(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. + */ +[LinkName("SDL_SetJoystickLED")] public static extern bool SetJoystickLED(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. + */ +[LinkName("SDL_SendJoystickEffect")] public static extern bool SendJoystickEffect(Joystick* joystick, void* data, c_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 + */ +[LinkName("SDL_CloseJoystick")] public static extern void CloseJoystick(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. + */ +[LinkName("SDL_GetJoystickConnectionState")] public static extern JoystickConnectionState GetJoystickConnectionState(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. + */ +[LinkName("SDL_GetJoystickPowerInfo")] public static extern PowerState GetJoystickPowerInfo(Joystick* joystick, out c_int percent); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_joystick_h_ */ \ No newline at end of file diff --git a/src/SDL_keyboard.bf b/src/SDL_keyboard.bf new file mode 100644 index 0000000..e16c3c8 --- /dev/null +++ b/src/SDL_keyboard.bf @@ -0,0 +1,619 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 + */ + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias KeyboardID = Uint32; + +/* 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 + */ +[LinkName("SDL_HasKeyboard")] public static extern bool HasKeyboard(); + +/** + * 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 + */ +[LinkName("SDL_GetKeyboards")] public static extern KeyboardID* GetKeyboards(out c_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 + */ +[LinkName("SDL_GetKeyboardNameForID")] public static extern c_char* GetKeyboardNameForID(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. + */ +[LinkName("SDL_GetKeyboardFocus")] public static extern Window* GetKeyboardFocus(); + +/** + * 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 + */ +[LinkName("SDL_GetKeyboardState")] public static extern bool* GetKeyboardState(c_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 + */ +[LinkName("SDL_ResetKeyboard")] public static extern void ResetKeyboard(); + +/** + * 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 + */ +[LinkName("SDL_GetModState")] public static extern Keymod GetModState(); + +/** + * 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 + */ +[LinkName("SDL_SetModState")] public static extern void SetModState(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 + */ +[LinkName("SDL_GetKeyFromScancode")] public static extern Keycode GetKeyFromScancode(Scancode scancode, 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 + */ +[LinkName("SDL_GetScancodeFromKey")] public static extern Scancode GetScancodeFromKey(Keycode key, 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 + */ +[LinkName("SDL_SetScancodeName")] public static extern bool SetScancodeName(Scancode scancode, c_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 + */ +[LinkName("SDL_GetScancodeName")] public static extern c_char* GetScancodeName(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 + */ +[LinkName("SDL_GetScancodeFromName")] public static extern Scancode GetScancodeFromName(c_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 + */ +[LinkName("SDL_GetKeyName")] public static extern c_char* GetKeyName(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 + */ +[LinkName("SDL_GetKeyFromName")] public static extern Keycode GetKeyFromName(c_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 + */ +[LinkName("SDL_StartTextInput")] public static extern bool StartTextInput(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 + */ +[AllowDuplicates] public enum TextInputType : c_int +{ + Text, /**< The input is text */ + TextName, /**< The input is a person's name */ + TextEmail, /**< The input is an e-mail address */ + TextUsername, /**< The input is a username */ + TextPasswordHidden, /**< The input is a secure password that is hidden */ + TextPasswordVisible, /**< The input is a secure password that is visible */ + Number, /**< The input is a number */ + NumberPasswordHidden, /**< The input is a secure PIN that is hidden */ + NumberPasswordVisible, /**< The input is a secure PIN that is visible */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum Capitalization : c_int +{ + eNone, /**< No auto-capitalization will be done */ + eSentences, /**< The first letter of sentences will be capitalized */ + eWords, /**< The first letter of words will be capitalized */ + eLetters, /**< All letters will be capitalized */ +} + +/** + * 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 + */ +[LinkName("SDL_StartTextInputWithProperties")] public static extern bool StartTextInputWithProperties(Window* window, PropertiesID props); + +public const let PROP_TEXTINPUT_TYPE_NUMBER = "SDL.textinput.type"; +public const let PROP_TEXTINPUT_CAPITALIZATION_NUMBER = "SDL.textinput.capitalization"; +public const let PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN = "SDL.textinput.autocorrect"; +public const let PROP_TEXTINPUT_MULTILINE_BOOLEAN = "SDL.textinput.multiline"; +public const let 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 + */ +[LinkName("SDL_TextInputActive")] public static extern bool TextInputActive(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 + */ +[LinkName("SDL_StopTextInput")] public static extern bool StopTextInput(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 + */ +[LinkName("SDL_ClearComposition")] public static extern bool ClearComposition(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 + */ +[LinkName("SDL_SetTextInputArea")] public static extern bool SetTextInputArea(Window* window, Rect* rect, c_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 + */ +[LinkName("SDL_GetTextInputArea")] public static extern bool GetTextInputArea(Window* window, Rect* rect, c_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 + */ +[LinkName("SDL_HasScreenKeyboardSupport")] public static extern bool HasScreenKeyboardSupport(); + +/** + * 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 + */ +[LinkName("SDL_ScreenKeyboardShown")] public static extern bool ScreenKeyboardShown(Window* window); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_keyboard_h_ */ \ No newline at end of file diff --git a/src/SDL_keycode.bf b/src/SDL_keycode.bf new file mode 100644 index 0000000..7dce994 --- /dev/null +++ b/src/SDL_keycode.bf @@ -0,0 +1,360 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 + */ + + + + + + + +/** + * 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 + */ +public enum Keycode : Uint32 +{ + ExtendedMask = (1u << 29), + ScancodeMask = (1u << 30), + Unknown = 0x00000000u, /**< 0 */ + Return = 0x0000000du, /**< '\r' */ + Escape = 0x0000001bu, /**< '\x1B' */ + Backspace = 0x00000008u, /**< '\b' */ + Tab = 0x00000009u, /**< '\t' */ + Space = 0x00000020u, /**< ' ' */ + Exclaim = 0x00000021u, /**< '!' */ + Dblapostrophe = 0x00000022u, /**< '"' */ + Hash = 0x00000023u, /**< '#' */ + Dollar = 0x00000024u, /**< '$' */ + Percent = 0x00000025u, /**< '%' */ + Ampersand = 0x00000026u, /**< '&' */ + Apostrophe = 0x00000027u, /**< '\'' */ + Leftparen = 0x00000028u, /**< '(' */ + Rightparen = 0x00000029u, /**< ')' */ + Asterisk = 0x0000002au, /**< '*' */ + Plus = 0x0000002bu, /**< '+' */ + Comma = 0x0000002cu, /**< ',' */ + Minus = 0x0000002du, /**< '-' */ + Period = 0x0000002eu, /**< '.' */ + Slash = 0x0000002fu, /**< '/' */ + _0 = 0x00000030u, /**< '0' */ + _1 = 0x00000031u, /**< '1' */ + _2 = 0x00000032u, /**< '2' */ + _3 = 0x00000033u, /**< '3' */ + _4 = 0x00000034u, /**< '4' */ + _5 = 0x00000035u, /**< '5' */ + _6 = 0x00000036u, /**< '6' */ + _7 = 0x00000037u, /**< '7' */ + _8 = 0x00000038u, /**< '8' */ + _9 = 0x00000039u, /**< '9' */ + Colon = 0x0000003au, /**< ':' */ + Semicolon = 0x0000003bu, /**< ';' */ + Less = 0x0000003cu, /**< '<' */ + Equals = 0x0000003du, /**< '=' */ + Greater = 0x0000003eu, /**< '>' */ + Question = 0x0000003fu, /**< '?' */ + At = 0x00000040u, /**< '@' */ + Leftbracket = 0x0000005bu, /**< '[' */ + Backslash = 0x0000005cu, /**< '\\' */ + Rightbracket = 0x0000005du, /**< ']' */ + Caret = 0x0000005eu, /**< '^' */ + Underscore = 0x0000005fu, /**< '_' */ + Grave = 0x00000060u, /**< '`' */ + A = 0x00000061u, /**< 'a' */ + B = 0x00000062u, /**< 'b' */ + C = 0x00000063u, /**< 'c' */ + D = 0x00000064u, /**< 'd' */ + E = 0x00000065u, /**< 'e' */ + F = 0x00000066u, /**< 'f' */ + G = 0x00000067u, /**< 'g' */ + H = 0x00000068u, /**< 'h' */ + I = 0x00000069u, /**< 'i' */ + J = 0x0000006au, /**< 'j' */ + K = 0x0000006bu, /**< 'k' */ + L = 0x0000006cu, /**< 'l' */ + M = 0x0000006du, /**< 'm' */ + N = 0x0000006eu, /**< 'n' */ + O = 0x0000006fu, /**< 'o' */ + P = 0x00000070u, /**< 'p' */ + Q = 0x00000071u, /**< 'q' */ + R = 0x00000072u, /**< 'r' */ + S = 0x00000073u, /**< 's' */ + T = 0x00000074u, /**< 't' */ + U = 0x00000075u, /**< 'u' */ + V = 0x00000076u, /**< 'v' */ + W = 0x00000077u, /**< 'w' */ + X = 0x00000078u, /**< 'x' */ + Y = 0x00000079u, /**< 'y' */ + Z = 0x0000007au, /**< 'z' */ + Leftbrace = 0x0000007bu, /**< '{' */ + Pipe = 0x0000007cu, /**< '|' */ + Rightbrace = 0x0000007du, /**< '}' */ + Tilde = 0x0000007eu, /**< '~' */ + Delete = 0x0000007fu, /**< '\x7F' */ + Plusminus = 0x000000b1u, /**< '\xB1' */ + Capslock = 0x40000039u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ + F1 = 0x4000003au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ + F2 = 0x4000003bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ + F3 = 0x4000003cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ + F4 = 0x4000003du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ + F5 = 0x4000003eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ + F6 = 0x4000003fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ + F7 = 0x40000040u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ + F8 = 0x40000041u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ + F9 = 0x40000042u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ + F10 = 0x40000043u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ + F11 = 0x40000044u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ + F12 = 0x40000045u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ + Printscreen = 0x40000046u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ + Scrolllock = 0x40000047u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ + Pause = 0x40000048u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ + Insert = 0x40000049u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ + Home = 0x4000004au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ + Pageup = 0x4000004bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ + End = 0x4000004du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ + Pagedown = 0x4000004eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ + Right = 0x4000004fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ + Left = 0x40000050u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ + Down = 0x40000051u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ + Up = 0x40000052u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ + Numlockclear = 0x40000053u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ + KpDivide = 0x40000054u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ + KpMultiply = 0x40000055u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ + KpMinus = 0x40000056u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ + KpPlus = 0x40000057u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ + KpEnter = 0x40000058u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ + Kp1 = 0x40000059u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ + Kp2 = 0x4000005au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ + Kp3 = 0x4000005bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ + Kp4 = 0x4000005cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ + Kp5 = 0x4000005du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ + Kp6 = 0x4000005eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ + Kp7 = 0x4000005fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ + Kp8 = 0x40000060u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ + Kp9 = 0x40000061u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ + Kp0 = 0x40000062u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ + KpPeriod = 0x40000063u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ + Application = 0x40000065u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ + Power = 0x40000066u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ + KpEquals = 0x40000067u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ + F13 = 0x40000068u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ + F14 = 0x40000069u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ + F15 = 0x4000006au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ + F16 = 0x4000006bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ + F17 = 0x4000006cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ + F18 = 0x4000006du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ + F19 = 0x4000006eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ + F20 = 0x4000006fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ + F21 = 0x40000070u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ + F22 = 0x40000071u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ + F23 = 0x40000072u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ + F24 = 0x40000073u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ + Execute = 0x40000074u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ + Help = 0x40000075u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ + Menu = 0x40000076u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ + Select = 0x40000077u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ + Stop = 0x40000078u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ + Again = 0x40000079u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ + Undo = 0x4000007au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ + Cut = 0x4000007bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ + Copy = 0x4000007cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ + Paste = 0x4000007du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ + Find = 0x4000007eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ + Mute = 0x4000007fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ + Volumeup = 0x40000080u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ + Volumedown = 0x40000081u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ + KpComma = 0x40000085u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ + KpEqualsas400 = 0x40000086u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ + Alterase = 0x40000099u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ + Sysreq = 0x4000009au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ + Cancel = 0x4000009bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ + Clear = 0x4000009cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ + Prior = 0x4000009du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ + Return2 = 0x4000009eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ + Separator = 0x4000009fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ + Out = 0x400000a0u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ + Oper = 0x400000a1u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ + Clearagain = 0x400000a2u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ + Crsel = 0x400000a3u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ + Exsel = 0x400000a4u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ + Kp00 = 0x400000b0u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ + Kp000 = 0x400000b1u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ + Thousandsseparator = 0x400000b2u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ + Decimalseparator = 0x400000b3u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ + Currencyunit = 0x400000b4u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ + Currencysubunit = 0x400000b5u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ + KpLeftparen = 0x400000b6u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ + KpRightparen = 0x400000b7u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ + KpLeftbrace = 0x400000b8u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ + KpRightbrace = 0x400000b9u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ + KpTab = 0x400000bau, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ + KpBackspace = 0x400000bbu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ + KpA = 0x400000bcu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ + KpB = 0x400000bdu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ + KpC = 0x400000beu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ + KpD = 0x400000bfu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ + KpE = 0x400000c0u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ + KpF = 0x400000c1u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ + KpXor = 0x400000c2u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ + KpPower = 0x400000c3u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ + KpPercent = 0x400000c4u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ + KpLess = 0x400000c5u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ + KpGreater = 0x400000c6u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ + KpAmpersand = 0x400000c7u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ + KpDblampersand = 0x400000c8u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ + KpVerticalbar = 0x400000c9u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ + KpDblverticalbar = 0x400000cau, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ + KpColon = 0x400000cbu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ + KpHash = 0x400000ccu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ + KpSpace = 0x400000cdu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ + KpAt = 0x400000ceu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ + KpExclam = 0x400000cfu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ + KpMemstore = 0x400000d0u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ + KpMemrecall = 0x400000d1u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ + KpMemclear = 0x400000d2u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ + KpMemadd = 0x400000d3u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ + KpMemsubtract = 0x400000d4u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ + KpMemmultiply = 0x400000d5u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ + KpMemdivide = 0x400000d6u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ + KpPlusminus = 0x400000d7u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ + KpClear = 0x400000d8u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ + KpClearentry = 0x400000d9u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ + KpBinary = 0x400000dau, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ + KpOctal = 0x400000dbu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ + KpDecimal = 0x400000dcu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ + KpHexadecimal = 0x400000ddu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ + Lctrl = 0x400000e0u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ + Lshift = 0x400000e1u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ + Lalt = 0x400000e2u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ + Lgui = 0x400000e3u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ + Rctrl = 0x400000e4u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ + Rshift = 0x400000e5u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ + Ralt = 0x400000e6u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ + Rgui = 0x400000e7u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ + Mode = 0x40000101u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ + Sleep = 0x40000102u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ + Wake = 0x40000103u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ + ChannelIncrement = 0x40000104u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ + ChannelDecrement = 0x40000105u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ + MediaPlay = 0x40000106u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ + MediaPause = 0x40000107u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ + MediaRecord = 0x40000108u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ + MediaFastForward = 0x40000109u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ + MediaRewind = 0x4000010au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ + MediaNextTrack = 0x4000010bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ + MediaPreviousTrack = 0x4000010cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ + MediaStop = 0x4000010du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ + MediaEject = 0x4000010eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ + MediaPlayPause = 0x4000010fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ + MediaSelect = 0x40000110u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ + AcNew = 0x40000111u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ + AcOpen = 0x40000112u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ + AcClose = 0x40000113u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ + AcExit = 0x40000114u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ + AcSave = 0x40000115u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ + AcPrint = 0x40000116u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ + AcProperties = 0x40000117u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ + AcSearch = 0x40000118u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ + AcHome = 0x40000119u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ + AcBack = 0x4000011au, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ + AcForward = 0x4000011bu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ + AcStop = 0x4000011cu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ + AcRefresh = 0x4000011du, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ + AcBookmarks = 0x4000011eu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ + Softleft = 0x4000011fu, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ + Softright = 0x40000120u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ + Call = 0x40000121u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ + Endcall = 0x40000122u, /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ + LeftTab = 0x20000001u, /**< Extended key Left Tab */ + Level5Shift = 0x20000002u, /**< Extended key Level 5 Shift */ + MultiKeyCompose = 0x20000003u, /**< Extended key Multi-key Compose */ + Lmeta = 0x20000004u, /**< Extended key Left Meta */ + Rmeta = 0x20000005u, /**< Extended key Right Meta */ + Lhyper = 0x20000006u, /**< Extended key Left Hyper */ + Rhyper = 0x20000007u, /**< Extended key Right Hyper */ +} /**< Extended key Right Hyper */ + +/** + * Valid key modifiers (possibly OR'd together). + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias Keymod = Uint16; + +public const let KMOD_NONE = 0x0000u;/**< no modifier is applicable. */ +public const let KMOD_LSHIFT = 0x0001u;/**< the left Shift key is down. */ +public const let KMOD_RSHIFT = 0x0002u;/**< the right Shift key is down. */ +public const let KMOD_LEVEL5 = 0x0004u;/**< the Level 5 Shift key is down. */ +public const let KMOD_LCTRL = 0x0040u;/**< the left Ctrl (Control) key is down. */ +public const let KMOD_RCTRL = 0x0080u;/**< the right Ctrl (Control) key is down. */ +public const let KMOD_LALT = 0x0100u;/**< the left Alt key is down. */ +public const let KMOD_RALT = 0x0200u;/**< the right Alt key is down. */ +public const let KMOD_LGUI = 0x0400u;/**< the left GUI key (often the Windows key) is down. */ +public const let KMOD_RGUI = 0x0800u;/**< the right GUI key (often the Windows key) is down. */ +public const let KMOD_NUM = 0x1000u;/**< the Num Lock key (may be located on an extended keypad) is down. */ +public const let KMOD_CAPS = 0x2000u;/**< the Caps Lock key is down. */ +public const let KMOD_MODE = 0x4000u;/**< the !AltGr key is down. */ +public const let KMOD_SCROLL = 0x8000u;/**< the Scroll Lock key is down. */ +public const let KMOD_CTRL = (KMOD_LCTRL | KMOD_RCTRL);/**< Any Ctrl key is down. */ +public const let KMOD_SHIFT = (KMOD_LSHIFT | KMOD_RSHIFT);/**< Any Shift key is down. */ +public const let KMOD_ALT = (KMOD_LALT | KMOD_RALT);/**< Any Alt key is down. */ +public const let KMOD_GUI = (KMOD_LGUI | KMOD_RGUI); +} + +/**< Any GUI key is down. */ + +/* SDL_keycode_h_ */ \ No newline at end of file diff --git a/src/SDL_loadso.bf b/src/SDL_loadso.bf new file mode 100644 index 0000000..eb924bc --- /dev/null +++ b/src/SDL_loadso.bf @@ -0,0 +1,156 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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: SharedObject */ + +/** + * # 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 + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * - Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * - Avoid namespace collisions. If you load a symbol from the library, it is + * 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. + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[CRepr] public struct 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 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_LoadFunction + * \sa SDL_UnloadObject + */ +[LinkName("SDL_LoadObject")] public static extern SharedObject* LoadObject(c_char* sofile); + +/** + * Look up the address of the named function in a shared object. + * + * This function pointer is no longer valid after calling SDL_UnloadObject(). + * + * This function can only look up C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * + * Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * + * If the requested function doesn't exist, NULL is returned. + * + * \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 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_LoadObject + */ +[LinkName("SDL_LoadFunction")] public static extern FunctionPointer LoadFunction(SharedObject* handle, c_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(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + */ +[LinkName("SDL_UnloadObject")] public static extern void UnloadObject(SharedObject* handle); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_loadso_h_ */ \ No newline at end of file diff --git a/src/SDL_locale.bf b/src/SDL_locale.bf new file mode 100644 index 0000000..d7d4097 --- /dev/null +++ b/src/SDL_locale.bf @@ -0,0 +1,128 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryLocale + * + * 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. + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + +/* *INDENT-OFF* */ + +/* *INDENT-ON* */ + + +/** + * 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 + */ +[CRepr] public struct Locale +{ + public c_char* language; /**< A language name, like "en" for English. */ + public c_char* country; /**< A country, like "US" for America. Can be NULL. */ +} + +/** + * Report the user's preferred locale. + * + * 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 + * code (such as "US" for the United States, "CA" for Canada, etc). Country + * might be NULL if there's no specific guidance on them (so you might get { + * "en", "US" } for American English, but { "en", NULL } means "English + * language, generically"). Language strings are never NULL, except to + * terminate the array. + * + * Please note that not all of these strings are 2 characters; some are three + * or more. + * + * The returned list of locales are in the order of the user's preference. For + * example, a German citizen that is fluent in US English and knows enough + * Japanese to navigate around Tokyo might have a list like: { "de", "en_US", + * "jp", NULL }. Someone from England might prefer British English (where + * "color" is spelled "colour", etc), but will settle for anything like it: { + * "en_GB", "en", NULL }. + * + * This function returns NULL on error, including when the platform does not + * supply this information at all. + * + * 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_EVENT_LOCALE_CHANGED event in this case, + * if possible, and you can call this function again to get an updated copy of + * preferred locales. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetPreferredLocales")] public static extern Locale** GetPreferredLocales(out c_int count); +} + +/* Ends C function definitions when using C++ */ + +/* *INDENT-OFF* */ + +/* *INDENT-ON* */ + + + +/* SDL_locale_h */ \ No newline at end of file diff --git a/src/SDL_log.bf b/src/SDL_log.bf new file mode 100644 index 0000000..64b019c --- /dev/null +++ b/src/SDL_log.bf @@ -0,0 +1,546 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +[AllowDuplicates] public enum LogCategory : c_int +{ + Application, + Error, + Assert, + System, + Audio, + Video, + Render, + Input, + Test, + Gpu, + + /* Reserved for future SDL library use */ + Reserved2, + Reserved3, + Reserved4, + Reserved5, + Reserved6, + Reserved7, + Reserved8, + Reserved9, + 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, + ... + }; + */ + Custom, +} + +/** + * The predefined log priorities + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum LogPriority : c_int +{ + Invalid, + Trace, + Verbose, + Debug, + Info, + Warn, + Error, + Critical, + Count, +} + + +/** + * 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 + */ +[LinkName("SDL_SetLogPriorities")] public static extern void SetLogPriorities(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 + */ +[LinkName("SDL_SetLogPriority")] public static extern void SetLogPriority(c_int category, 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 + */ +[LinkName("SDL_GetLogPriority")] public static extern LogPriority GetLogPriority(c_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 + */ +[LinkName("SDL_ResetLogPriorities")] public static extern void ResetLogPriorities(); + +/** + * 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 + */ +[LinkName("SDL_SetLogPriorityPrefix")] public static extern bool SetLogPriorityPrefix(LogPriority priority, c_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 + */ +[LinkName("SDL_Log")] public static extern void Log(c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogTrace")] public static extern void LogTrace(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogVerbose")] public static extern void LogVerbose(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogDebug")] public static extern void LogDebug(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogInfo")] public static extern void LogInfo(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogWarn")] public static extern void LogWarn(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogError")] public static extern void LogError(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogCritical")] public static extern void LogCritical(c_int category, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogMessage")] public static extern void LogMessage(c_int category, LogPriority priority, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_LogMessageV")] public static extern void LogMessageV(c_int category, LogPriority priority, c_char* fmt, VarArgs ap); + +/** + * 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. + */ +public function void LogOutputFunction(void* userdata, c_int category, LogPriority priority, c_char* message); + +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +[LinkName("SDL_GetDefaultLogOutputFunction")] public static extern LogOutputFunction GetDefaultLogOutputFunction(); + +/** + * 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 + */ +[LinkName("SDL_GetLogOutputFunction")] public static extern void GetLogOutputFunction(LogOutputFunction* callback, out 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 + */ +[LinkName("SDL_SetLogOutputFunction")] public static extern void SetLogOutputFunction(LogOutputFunction callback, void* userdata); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_log_h_ */ \ No newline at end of file diff --git a/src/SDL_main.bf b/src/SDL_main.bf new file mode 100644 index 0000000..a284398 --- /dev/null +++ b/src/SDL_main.bf @@ -0,0 +1,683 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 + */ + + + + + + + + + + + +/** + * 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. + */ + + +/** + * 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 + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + + + + + + + + + + + + /* Private platforms may have their own ideas about entry points. */ + + + + /* 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 + */ + + + + /* 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. + */ + + + + /* 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. + */ + + + + /* 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. + */ + + + /* 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. + */ + + + + /* 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 + */ + + + + /* 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 + */ + + + + + + + + + + + /* + 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 + */ + + + +/* SDL_MAIN_HANDLED */ + + + + +/** + * 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 + */ + + + +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ + + +/* usually this is empty */ + +/* SDL_MAIN_EXPORTED */ + + + + + + + + + + + +/* + * 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. + */ + + +/** + * App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps. + * + * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a + * standard "main" function, you should not supply this. + * + * This function is called by SDL once, at startup. The function should + * initialize whatever is necessary, possibly create windows and open audio + * devices, etc. The `argc` and `argv` parameters work like they would with a + * standard "main" function. + * + * This function should not go into an infinite mainloop; it should do any + * one-time setup it requires and then return. + * + * The app may optionally assign a pointer to `*appstate`. This pointer will + * be provided on every future call to the other entry points, to allow + * application state to be preserved between functions without the app needing + * to use a global variable. If this isn't set, the pointer will be NULL in + * future entry points. + * + * If this function returns SDL_APP_CONTINUE, the app will proceed to normal + * operation, and will begin receiving repeated calls to SDL_AppIterate and + * SDL_AppEvent for the life of the program. If this function returns + * SDL_APP_FAILURE, SDL will call SDL_AppQuit and terminate the process with + * an exit code that reports an error to the platform. If it returns + * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code + * that reports success to the platform. + * + * This function is called by SDL on the main thread. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AppIterate + * \sa SDL_AppEvent + * \sa SDL_AppQuit + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/* 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. + */ +public function c_int main_func(c_int argc, c_char**); + +/** + * 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. + */ +[LinkName("SDL_main")] public static extern c_int main(c_int argc, c_char** argv); + +/** + * Circumvent failure of SDL_Init() when not using SDL_main() as an entry + * point. + * + * This function is defined in SDL_main.h, along with the preprocessor rule to + * redefine main() as SDL_main(). Thus to ensure that your main() function + * will not be changed it is necessary to define SDL_MAIN_HANDLED before + * including SDL.h. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Init + */ +[LinkName("SDL_SetMainReady")] public static extern void SetMainReady(); + +/** + * 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. + */ +[LinkName("SDL_RunApp")] public static extern c_int RunApp(c_int argc, c_char** argv, 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. + */ +[LinkName("SDL_EnterAppMainCallbacks")] public static extern c_int EnterAppMainCallbacks(c_int argc, c_char** argv, AppInit_func appinit, AppIterate_func appiter, AppEvent_func appevent, AppQuit_func appquit); + + + + +/** + * 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. + * + * \since This function is available since SDL 3.2.0. + */ + + +/** + * Deregister the win32 window class from an SDL_RegisterApp call. + * + * This can be called to undo the effects of SDL_RegisterApp. + * + * Most applications do not need to, and should not, call this directly; SDL + * will call it when deinitializing the video subsystem. + * + * It is safe to call this multiple times, as long as every call is eventually + * paired with a prior call to SDL_RegisterApp. The window class will only be + * deregistered when the registration counter in SDL_RegisterApp decrements to + * zero through calls to this function. + * + * \since This function is available since SDL 3.2.0. + */ + + +/* defined(SDL_PLATFORM_WINDOWS) */ + +/** + * Callback from the application to let the suspend continue. + * + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GDKSuspendComplete")] public static extern void GDKSuspendComplete(); +} + +/* include header-only SDL_main implementations */ + + /* platforms which main (-equivalent) can be implemented in plain C */ + + + + +/* SDL_main_h_ */ \ No newline at end of file diff --git a/src/SDL_main_impl.bf b/src/SDL_main_impl.bf new file mode 100644 index 0000000..5dea280 --- /dev/null +++ b/src/SDL_main_impl.bf @@ -0,0 +1,164 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 */ + + + + + + + + +/* 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 */ + + + /* 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) */ + + + + + + + + /* currently there are no platforms that _need_ a magic entry point here + for callbacks, but if one shows up, implement it here. */ + + /* 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. */ + + + + + + + + /* platform-specific tests */ + + /* 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 */ + + + + /* Private platforms may have their own ideas about entry points. */ + + + + + /* these defines/typedefs are needed for the WinMain() definition */ + + + + + + + + + /* The VC++ compiler needs main/wmain defined, but not for GDK */ + + + /* This is where execution begins [console apps] */ + + + + + + + + + /* ANSI */ + + + + + + + /* UNICODE */ + + /* _MSC_VER && ! SDL_PLATFORM_GDK */ + + /* This is where execution begins [windowed apps and GDK] */ + + + + + + + + /* ANSI */ + + + + + + + + + + + + /* extern "C" */ + + + /* end of SDL_PLATFORM_WINDOWS impls */ + + /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ + [CLink] public static extern c_int main(c_int argc, c_char** argv); + + + + + /* end of impls for standard-conforming platforms */ + + /* SDL_PLATFORM_WIN32 etc */ + + /* !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 */ + +} + + + +/* SDL_MAIN_HANDLED */ + +/* SDL_main_impl_h_ */ \ No newline at end of file diff --git a/src/SDL_messagebox.bf b/src/SDL_messagebox.bf new file mode 100644 index 0000000..bb10abb --- /dev/null +++ b/src/SDL_messagebox.bf @@ -0,0 +1,238 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # 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. + */ + + + + + + +/* For SDL_Window */ + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * Message box flags. + * + * If supported will display warning icon, etc. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum MessageBoxFlags : Uint32 {} + + +public const let MESSAGEBOX_ERROR = 0x00000010u;/**< error dialog */ +public const let MESSAGEBOX_WARNING = 0x00000020u;/**< warning dialog */ +public const let MESSAGEBOX_INFORMATION = 0x00000040u;/**< informational dialog */ +public const let MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT = 0x00000080u;/**< buttons placed left to right */ +public const let MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT = 0x00000100u;/**< buttons placed right to left */ + +/** + * SDL_MessageBoxButtonData flags. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum MessageBoxButtonFlags : Uint32 {} + + +public const let MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001u;/**< Marks the default button when return is hit */ +public const let 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. + */ +[CRepr] public struct MessageBoxButtonData +{ + public MessageBoxButtonFlags flags; + public c_int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */ + public c_char* text; /**< The UTF-8 button text */ +} + +/** + * RGB value used in a message box color scheme + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MessageBoxColor +{ + public Uint8 r; public Uint8 g; public Uint8 b; +} + +/** + * An enumeration of indices inside the colors array of + * SDL_MessageBoxColorScheme. + */ +[AllowDuplicates] public enum MessageBoxColorType : c_int +{ + Background, + ext, + ButtonBorder, + ButtonBackground, + ButtonSelected, + Count, /**< Size of the colors array of SDL_MessageBoxColorScheme. */ +} + +/** + * A set of colors to use for message box dialogs + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MessageBoxColorScheme +{ + public MessageBoxColor[5] colors; +} + +/** + * MessageBox structure containing title, text, window, etc. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct MessageBoxData +{ + public MessageBoxFlags flags; + public Window* window; /**< Parent window, can be NULL */ + public c_char* title; /**< UTF-8 title */ + public c_char* message; /**< UTF-8 message text */ + + public c_int numbuttons; + public MessageBoxButtonData* buttons; + + public MessageBoxColorScheme* colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */ +} + +/** + * Create a modal message box. + * + * If your needs aren't complex, it might be easier to use + * SDL_ShowSimpleMessageBox. + * + * This function should be called on the thread that created the parent + * window, or on the main thread if the messagebox has no parent. It will + * block execution of that thread until the user clicks a button or closes the + * messagebox. + * + * This function may be called at any time, even before SDL_Init(). This makes + * it useful for reporting errors like a failure to create a renderer or + * OpenGL context. + * + * On X11, SDL rolls its own dialog box with X11 primitives instead of a + * formal toolkit like GTK+ or Qt. + * + * Note that if SDL_Init() would fail because there isn't any available video + * target, this function is likely to fail for the same reasons. If this is a + * concern, check the return value from this function and fall back to writing + * to stderr if you can. + * + * \param messageboxdata the SDL_MessageBoxData structure with title, text and + * other options. + * \param buttonid the pointer to which user id of hit button should be + * copied. + * \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_ShowSimpleMessageBox + */ +[LinkName("SDL_ShowMessageBox")] public static extern bool ShowMessageBox(MessageBoxData* messageboxdata, c_int* buttonid); + +/** + * Display a simple modal message box. + * + * If your needs aren't complex, this function is preferred over + * SDL_ShowMessageBox. + * + * `flags` may be any of the following: + * + * - `SDL_MESSAGEBOX_ERROR`: error dialog + * - `SDL_MESSAGEBOX_WARNING`: warning dialog + * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog + * + * This function should be called on the thread that created the parent + * window, or on the main thread if the messagebox has no parent. It will + * block execution of that thread until the user clicks a button or closes the + * messagebox. + * + * This function may be called at any time, even before SDL_Init(). This makes + * it useful for reporting errors like a failure to create a renderer or + * OpenGL context. + * + * On X11, SDL rolls its own dialog box with X11 primitives instead of a + * formal toolkit like GTK+ or Qt. + * + * Note that if SDL_Init() would fail because there isn't any available video + * target, this function is likely to fail for the same reasons. If this is a + * concern, check the return value from this function and fall back to writing + * to stderr if you can. + * + * \param flags an SDL_MessageBoxFlags value. + * \param title UTF-8 title text. + * \param message UTF-8 message text. + * \param window the parent window, or NULL for no parent. + * \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_ShowMessageBox + */ +[LinkName("SDL_ShowSimpleMessageBox")] public static extern bool ShowSimpleMessageBox(MessageBoxFlags flags, c_char* title, c_char* message, Window* window); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_messagebox_h_ */ \ No newline at end of file diff --git a/src/SDL_metal.bf b/src/SDL_metal.bf new file mode 100644 index 0000000..1104b84 --- /dev/null +++ b/src/SDL_metal.bf @@ -0,0 +1,118 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryMetal + * + * 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias MetalView = void*; + +/** + * \name Metal support functions + */ +/* @{ */ + +/** + * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified + * window. + * + * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on + * its own. It is up to user code to do that. + * + * The returned handle can be casted directly to a NSView or UIView. To access + * the backing CAMetalLayer, call SDL_Metal_GetLayer(). + * + * \param window the window. + * \returns handle NSView or UIView. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Metal_DestroyView + * \sa SDL_Metal_GetLayer + */ +[LinkName("SDL_Metal_CreateView")] public static extern MetalView Metal_CreateView(Window* window); + +/** + * Destroy an existing SDL_MetalView object. + * + * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was + * called after SDL_CreateWindow. + * + * \param view the SDL_MetalView object. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Metal_CreateView + */ +[LinkName("SDL_Metal_DestroyView")] public static extern void Metal_DestroyView(MetalView view); + +/** + * Get a pointer to the backing CAMetalLayer for the given view. + * + * \param view the SDL_MetalView object. + * \returns a pointer. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_Metal_GetLayer")] public static extern void* Metal_GetLayer(MetalView view); +} + +/* @} */ /* Metal support functions */ + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_metal_h_ */ \ No newline at end of file diff --git a/src/SDL_misc.bf b/src/SDL_misc.bf new file mode 100644 index 0000000..b9d568a --- /dev/null +++ b/src/SDL_misc.bf @@ -0,0 +1,89 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryMisc + * + * SDL API functions that don't fit elsewhere. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * Open a URL/URI in the browser or other appropriate external application. + * + * Open a URL in a separate, system-provided application. How this works will + * vary wildly depending on the platform. This will likely launch what makes + * sense to handle a specific URL's protocol (a web browser for `http://`, + * etc), but it might also be able to launch file managers for directories and + * other things. + * + * What happens when you open a URL varies wildly as well: your game window + * may lose focus (and may or may not lose focus if your game was fullscreen + * or grabbing input at the time). On mobile devices, your app will likely + * move to the background or your process might be paused. Any given platform + * may or may not handle a given URL. + * + * If this is unimplemented (or simply unavailable) for a platform, this will + * fail with an error. A successful result does not mean the URL loaded, just + * that we launched _something_ to handle it (or at least believe we did). + * + * 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 + * local files, if supported. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_OpenURL")] public static extern bool OpenURL(c_char* url); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_misc_h_ */ \ No newline at end of file diff --git a/src/SDL_mouse.bf b/src/SDL_mouse.bf new file mode 100644 index 0000000..58ec8d8 --- /dev/null +++ b/src/SDL_mouse.bf @@ -0,0 +1,840 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias MouseID = Uint32; + +/** + * The structure used to identify an SDL cursor. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct Cursor; + +/** + * Cursor types for SDL_CreateSystemCursor(). + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum SystemCursor : c_int +{ + Default, /**< Default cursor. Usually an arrow. */ + Text, /**< Text selection. Usually an I-beam. */ + Wait, /**< Wait. Usually an hourglass or watch or spinning ball. */ + Crosshair, /**< Crosshair. */ + Progress, /**< Program is busy but still interactive. Usually it's WAIT with an arrow. */ + NwseResize, /**< Double arrow pointing northwest and southeast. */ + NeswResize, /**< Double arrow pointing northeast and southwest. */ + EwResize, /**< Double arrow pointing west and east. */ + NsResize, /**< Double arrow pointing north and south. */ + Move, /**< Four pointed arrow pointing north, south, east, and west. */ + NotAllowed, /**< Not permitted. Usually a slashed circle or crossbones. */ + Pointer, /**< Pointer that indicates a link. Usually a pointing hand. */ + NwResize, /**< Window resize top-left. This may be a single arrow or a double arrow like NWSE_RESIZE. */ + NResize, /**< Window resize top. May be NS_RESIZE. */ + NeResize, /**< Window resize top-right. May be NESW_RESIZE. */ + EResize, /**< Window resize right. May be EW_RESIZE. */ + SeResize, /**< Window resize bottom-right. May be NWSE_RESIZE. */ + SResize, /**< Window resize bottom. May be NS_RESIZE. */ + SwResize, /**< Window resize bottom-left. May be NESW_RESIZE. */ + WResize, /**< Window resize left. May be EW_RESIZE. */ + Count, +} + +/** + * Scroll direction types for the Scroll event + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum MouseWheelDirection : c_int +{ + Normal, /**< The scroll direction is normal */ + Flipped, /**< The scroll direction is flipped / natural */ +} + +/** + * Animated cursor frame info. + * + * \since This struct is available since SDL 3.4.0. + */ +[CRepr] public struct CursorFrameInfo +{ + public Surface* surface; /**< The surface data for this frame */ + public Uint32 duration; /**< The frame duration in milliseconds (a duration of 0 is infinite) */ +} + +/** + * 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 + */ +[AllowDuplicates] public enum MouseButtonFlags : Uint32 +{ + Left = 1, + Middle = 2, + Right = 3, + X1 = 4, + X2 = 5, + Lmask = BUTTON_MASK(Left), + Mmask = BUTTON_MASK(Middle), + Rmask = BUTTON_MASK(Right), + X1mask = BUTTON_MASK(X1), + X2mask = BUTTON_MASK(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 + */ +} + +/** + * 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 + */ +public function void MouseMotionTransformCallback(void* userdata, Uint64 timestamp, Window* window, 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 + */ +[LinkName("SDL_HasMouse")] public static extern bool HasMouse(); + +/** + * 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 + */ +[LinkName("SDL_GetMice")] public static extern MouseID* GetMice(out c_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 + */ +[LinkName("SDL_GetMouseNameForID")] public static extern c_char* GetMouseNameForID(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. + */ +[LinkName("SDL_GetMouseFocus")] public static extern Window* GetMouseFocus(); + +/** + * 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 + */ +[LinkName("SDL_GetMouseState")] public static extern MouseButtonFlags GetMouseState(out float x, out 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 + */ +[LinkName("SDL_GetGlobalMouseState")] public static extern MouseButtonFlags GetGlobalMouseState(out float x, out 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 + */ +[LinkName("SDL_GetRelativeMouseState")] public static extern MouseButtonFlags GetRelativeMouseState(out float x, out 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 + */ +[LinkName("SDL_WarpMouseInWindow")] public static extern void WarpMouseInWindow(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 + */ +[LinkName("SDL_WarpMouseGlobal")] public static extern bool 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. + */ +[LinkName("SDL_SetRelativeMouseTransform")] public static extern bool SetRelativeMouseTransform(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 + */ +[LinkName("SDL_SetWindowRelativeMouseMode")] public static extern bool SetWindowRelativeMouseMode(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 + */ +[LinkName("SDL_GetWindowRelativeMouseMode")] public static extern bool GetWindowRelativeMouseMode(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 + */ +[LinkName("SDL_CaptureMouse")] public static extern bool 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 + */ +[LinkName("SDL_CreateCursor")] public static extern Cursor* CreateCursor(Uint8* data, Uint8* mask, c_int w, c_int h, c_int hot_x, c_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 + */ +[LinkName("SDL_CreateColorCursor")] public static extern Cursor* CreateColorCursor(Surface* surface, c_int hot_x, c_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 + */ +[LinkName("SDL_CreateAnimatedCursor")] public static extern Cursor* CreateAnimatedCursor(CursorFrameInfo* frames, c_int frame_count, c_int hot_x, c_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 + */ +[LinkName("SDL_CreateSystemCursor")] public static extern Cursor* CreateSystemCursor(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 + */ +[LinkName("SDL_SetCursor")] public static extern bool SetCursor(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 + */ +[LinkName("SDL_GetCursor")] public static extern Cursor* GetCursor(); + +/** + * 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. + */ +[LinkName("SDL_GetDefaultCursor")] public static extern Cursor* GetDefaultCursor(); + +/** + * 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 + */ +[LinkName("SDL_DestroyCursor")] public static extern void DestroyCursor(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 + */ +[LinkName("SDL_ShowCursor")] public static extern bool ShowCursor(); + +/** + * 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 + */ +[LinkName("SDL_HideCursor")] public static extern bool HideCursor(); + +/** + * 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 + */ +[LinkName("SDL_CursorVisible")] public static extern bool CursorVisible(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_mouse_h_ */ \ No newline at end of file diff --git a/src/SDL_mutex.bf b/src/SDL_mutex.bf new file mode 100644 index 0000000..95d1b64 --- /dev/null +++ b/src/SDL_mutex.bf @@ -0,0 +1,1083 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + + + + +/** + * # 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. + */ + + + + + + + + +/** + * 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" + * ``` + */ + + + + + +/* no-op */ + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/** + * 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. + */ + + + +/******************************************************************************/ + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * \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. + */ +[CRepr] public struct Mutex; + +/** + * Create a new mutex. + * + * All newly-created mutexes begin in the _unlocked_ state. + * + * Calls to SDL_LockMutex() will not return while the mutex is locked by + * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. + * + * SDL mutexes are reentrant. + * + * \returns the initialized and unlocked mutex or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyMutex + * \sa SDL_LockMutex + * \sa SDL_TryLockMutex + * \sa SDL_UnlockMutex + */ +[LinkName("SDL_CreateMutex")] public static extern Mutex* CreateMutex(); + +/** + * Lock the mutex. + * + * This will block until the mutex is available, which is to say it is in the + * unlocked state and the OS has chosen the caller as the next thread to lock + * it. Of all threads waiting to lock the mutex, only one may do so at a time. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * This function does not fail; if mutex is NULL, it will return immediately + * having locked nothing. If the mutex is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param mutex the mutex to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryLockMutex + * \sa SDL_UnlockMutex + */ +[LinkName("SDL_LockMutex")] public static extern void LockMutex(Mutex* mutex); + +/** + * Try to lock a mutex without blocking. + * + * This works just like SDL_LockMutex(), but if the mutex is not available, + * this function returns false immediately. + * + * This technique is useful if you need exclusive access to a resource but + * don't want to wait for it, and will return to it to try again later. + * + * This function returns true if passed a NULL mutex. + * + * \param mutex the mutex to try to lock. + * \returns true on success, false if the mutex would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockMutex + * \sa SDL_UnlockMutex + */ +[LinkName("SDL_TryLockMutex")] public static extern bool TryLockMutex(Mutex* mutex); + +/** + * Unlock the mutex. + * + * It is legal for the owning thread to lock an already-locked mutex. It must + * unlock it the same number of times before it is actually made available for + * other threads in the system (this is known as a "recursive mutex"). + * + * It is illegal to unlock a mutex that has not been locked by the current + * thread, and doing so results in undefined behavior. + * + * \param mutex the mutex to unlock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockMutex + * \sa SDL_TryLockMutex + */ +[LinkName("SDL_UnlockMutex")] public static extern void UnlockMutex(Mutex* mutex); + +/** + * Destroy a mutex created with SDL_CreateMutex(). + * + * This function must be called on any mutex that is no longer needed. Failure + * to destroy a mutex will result in a system memory or resource leak. While + * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt + * to destroy a locked mutex, and may result in undefined behavior depending + * on the platform. + * + * \param mutex the mutex to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateMutex + */ +[LinkName("SDL_DestroyMutex")] public static extern void DestroyMutex(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. + */ +[CRepr] public struct RWLock; + +/** + * Create a new read/write lock. + * + * A read/write lock is useful for situations where you have multiple threads + * trying to access a resource that is rarely updated. All threads requesting + * a read-only lock will be allowed to run in parallel; if a thread requests a + * write lock, it will be provided exclusive access. This makes it safe for + * multiple threads to use a resource at the same time if they promise not to + * change it, and when it has to be changed, the rwlock will serve as a + * gateway to make sure those changes can be made safely. + * + * In the right situation, a rwlock can be more efficient than a mutex, which + * only lets a single thread proceed at a time, even if it won't be modifying + * the data. + * + * All newly-created read/write locks begin in the _unlocked_ state. + * + * Calls to SDL_LockRWLockForReading() and SDL_LockRWLockForWriting will not + * return while the rwlock is locked _for writing_ by another thread. See + * SDL_TryLockRWLockForReading() and SDL_TryLockRWLockForWriting() to attempt + * to lock without blocking. + * + * SDL read/write locks are only recursive for read-only locks! They are not + * guaranteed to be fair, or provide access in a FIFO manner! They are not + * guaranteed to favor writers. You may not lock a rwlock for both read-only + * and write access at the same time from the same thread (so you can't + * promote your read-only lock to a write lock without unlocking first). + * + * \returns the initialized and unlocked read/write lock or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyRWLock + * \sa SDL_LockRWLockForReading + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +[LinkName("SDL_CreateRWLock")] public static extern RWLock* CreateRWLock(); + +/** + * Lock the read/write lock for _read only_ operations. + * + * This will block until the rwlock is available, which is to say it is not + * locked for writing by any other thread. Of all threads waiting to lock the + * rwlock, all may do so at the same time as long as they are requesting + * read-only access; if a thread wants to lock for writing, only one may do so + * at a time, and no other threads, read-only or not, may hold the lock at the + * same time. + * + * It is legal for the owning thread to lock an already-locked rwlock for + * reading. It must unlock it the same number of times before it is actually + * made available for other threads in the system (this is known as a + * "recursive rwlock"). + * + * Note that locking for writing is not recursive (this is only available to + * read-only locks). + * + * It is illegal to request a read-only lock from a thread that already holds + * the write lock. Doing so results in undefined behavior. Unlock the write + * lock before requesting a read-only lock. (But, of course, if you have the + * write lock, you don't need further locks to read in any case.) + * + * This function does not fail; if rwlock is NULL, it will return immediately + * having locked nothing. If the rwlock is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param rwlock the read/write lock to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_UnlockRWLock + */ +[LinkName("SDL_LockRWLockForReading")] public static extern void LockRWLockForReading(RWLock* rwlock); + +/** + * Lock the read/write lock for _write_ operations. + * + * This will block until the rwlock is available, which is to say it is not + * locked for reading or writing by any other thread. Only one thread may hold + * the lock when it requests write access; all other threads, whether they + * also want to write or only want read-only access, must wait until the + * writer thread has released the lock. + * + * It is illegal for the owning thread to lock an already-locked rwlock for + * writing (read-only may be locked recursively, writing can not). Doing so + * results in undefined behavior. + * + * It is illegal to request a write lock from a thread that already holds a + * read-only lock. Doing so results in undefined behavior. Unlock the + * read-only lock before requesting a write lock. + * + * This function does not fail; if rwlock is NULL, it will return immediately + * having locked nothing. If the rwlock is valid, this function will always + * block until it can lock the mutex, and return with it locked. + * + * \param rwlock the read/write lock to lock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +[LinkName("SDL_LockRWLockForWriting")] public static extern void LockRWLockForWriting(RWLock* rwlock); + +/** + * Try to lock a read/write lock _for reading_ without blocking. + * + * This works just like SDL_LockRWLockForReading(), but if the rwlock is not + * available, then this function returns false immediately. + * + * This technique is useful if you need access to a resource but don't want to + * wait for it, and will return to it to try again later. + * + * Trying to lock for read-only access can succeed if other threads are + * holding read-only locks, as this won't prevent access. + * + * This function returns true if passed a NULL rwlock. + * + * \param rwlock the rwlock to try to lock. + * \returns true on success, false if the lock would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + * \sa SDL_UnlockRWLock + */ +[LinkName("SDL_TryLockRWLockForReading")] public static extern bool TryLockRWLockForReading(RWLock* rwlock); + +/** + * Try to lock a read/write lock _for writing_ without blocking. + * + * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not + * available, then this function returns false immediately. + * + * This technique is useful if you need exclusive access to a resource but + * don't want to wait for it, and will return to it to try again later. + * + * It is illegal for the owning thread to lock an already-locked rwlock for + * writing (read-only may be locked recursively, writing can not). Doing so + * results in undefined behavior. + * + * It is illegal to request a write lock from a thread that already holds a + * read-only lock. Doing so results in undefined behavior. Unlock the + * read-only lock before requesting a write lock. + * + * This function returns true if passed a NULL rwlock. + * + * \param rwlock the rwlock to try to lock. + * \returns true on success, false if the lock would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_UnlockRWLock + */ +[LinkName("SDL_TryLockRWLockForWriting")] public static extern bool TryLockRWLockForWriting(RWLock* rwlock); + +/** + * Unlock the read/write lock. + * + * Use this function to unlock the rwlock, whether it was locked for read-only + * or write operations. + * + * It is legal for the owning thread to lock an already-locked read-only lock. + * It must unlock it the same number of times before it is actually made + * available for other threads in the system (this is known as a "recursive + * rwlock"). + * + * It is illegal to unlock a rwlock that has not been locked by the current + * thread, and doing so results in undefined behavior. + * + * \param rwlock the rwlock to unlock. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockRWLockForReading + * \sa SDL_LockRWLockForWriting + * \sa SDL_TryLockRWLockForReading + * \sa SDL_TryLockRWLockForWriting + */ +[LinkName("SDL_UnlockRWLock")] public static extern void UnlockRWLock(RWLock* rwlock); + +/** + * Destroy a read/write lock created with SDL_CreateRWLock(). + * + * This function must be called on any read/write lock that is no longer + * needed. Failure to destroy a rwlock will result in a system memory or + * resource leak. While it is safe to destroy a rwlock that is _unlocked_, it + * is not safe to attempt to destroy a locked rwlock, and may result in + * undefined behavior depending on the platform. + * + * \param rwlock the rwlock to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateRWLock + */ +[LinkName("SDL_DestroyRWLock")] public static extern void DestroyRWLock(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. + */ +[CRepr] public struct Semaphore; + +/** + * Create a semaphore. + * + * This function creates a new semaphore and initializes it with the value + * `initial_value`. Each wait operation on the semaphore will atomically + * decrement the semaphore value and potentially block if the semaphore value + * is 0. Each post operation will atomically increment the semaphore value and + * wake waiting threads and allow them to retry the wait operation. + * + * \param initial_value the starting value of the semaphore. + * \returns a new semaphore or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroySemaphore + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_GetSemaphoreValue + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +[LinkName("SDL_CreateSemaphore")] public static extern Semaphore* CreateSemaphore(Uint32 initial_value); + +/** + * Destroy a semaphore. + * + * It is not safe to destroy a semaphore if there are threads currently + * waiting on it. + * + * \param sem the semaphore to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateSemaphore + */ +[LinkName("SDL_DestroySemaphore")] public static extern void DestroySemaphore(Semaphore* sem); + +/** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until the semaphore pointed to by + * `sem` has a positive value, and then atomically decrement the semaphore + * value. + * + * This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with + * a time length of -1. + * + * \param sem the semaphore wait on. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +[LinkName("SDL_WaitSemaphore")] public static extern void WaitSemaphore(Semaphore* sem); + +/** + * See if a semaphore has a positive value and decrement it if it does. + * + * This function checks to see if the semaphore pointed to by `sem` has a + * positive value and atomically decrements the semaphore value if it does. If + * the semaphore doesn't have a positive value, the function immediately + * returns false. + * + * \param sem the semaphore to wait on. + * \returns true if the wait succeeds, false if the wait would block. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +[LinkName("SDL_TryWaitSemaphore")] public static extern bool TryWaitSemaphore(Semaphore* sem); + +/** + * Wait until a semaphore has a positive value and then decrements it. + * + * This function suspends the calling thread until either the semaphore + * pointed to by `sem` has a positive value or the specified time has elapsed. + * If the call is successful it will atomically decrement the semaphore value. + * + * \param sem the semaphore to wait on. + * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if the wait succeeds or false if the wait times out. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalSemaphore + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphore + */ +[LinkName("SDL_WaitSemaphoreTimeout")] public static extern bool WaitSemaphoreTimeout(Semaphore* sem, Sint32 timeoutMS); + +/** + * Atomically increment a semaphore's value and wake waiting threads. + * + * \param sem the semaphore to increment. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryWaitSemaphore + * \sa SDL_WaitSemaphore + * \sa SDL_WaitSemaphoreTimeout + */ +[LinkName("SDL_SignalSemaphore")] public static extern void SignalSemaphore(Semaphore* sem); + +/** + * Get the current value of a semaphore. + * + * \param sem the semaphore to query. + * \returns the current value of the semaphore. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetSemaphoreValue")] public static extern Uint32 GetSemaphoreValue(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. + */ +[CRepr] public struct Condition; + +/** + * Create a condition variable. + * + * \returns a new condition variable or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BroadcastCondition + * \sa SDL_SignalCondition + * \sa SDL_WaitCondition + * \sa SDL_WaitConditionTimeout + * \sa SDL_DestroyCondition + */ +[LinkName("SDL_CreateCondition")] public static extern Condition* CreateCondition(); + +/** + * Destroy a condition variable. + * + * \param cond the condition variable to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateCondition + */ +[LinkName("SDL_DestroyCondition")] public static extern void DestroyCondition(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 + */ +[LinkName("SDL_SignalCondition")] public static extern void SignalCondition(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 + */ +[LinkName("SDL_BroadcastCondition")] public static extern void BroadcastCondition(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 + */ +[LinkName("SDL_WaitCondition")] public static extern void WaitCondition(Condition* cond, 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 + */ +[LinkName("SDL_WaitConditionTimeout")] public static extern bool WaitConditionTimeout(Condition* cond, 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. + */ +[AllowDuplicates] public enum InitStatus : c_int +{ + Uninitialized, + Initializing, + Initialized, + Uninitializing, +} + +/** + * 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. + */ +[CRepr] public struct InitState +{ + public AtomicInt status; + public ThreadID thread; + public void* reserved; +} + +/** + * 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 + */ +[LinkName("SDL_ShouldInit")] public static extern bool ShouldInit(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 + */ +[LinkName("SDL_ShouldQuit")] public static extern bool ShouldQuit(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 + */ +[LinkName("SDL_SetInitialized")] public static extern void SetInitialized(InitState* state, bool initialized); +} + +/* @} */ /* Thread-safe initialization state functions */ + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_mutex_h_ */ \ No newline at end of file diff --git a/src/SDL_oldnames.bf b/src/SDL_oldnames.bf new file mode 100644 index 0000000..7790668 --- /dev/null +++ b/src/SDL_oldnames.bf @@ -0,0 +1,1335 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +/* + 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 + */ + + + + + + +/* 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 + */ + + +/* ##SDL_atomic.h */ + + + + + + + + + + + + +/* ##SDL_audio.h */ + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_cpuinfo.h */ + + + +/* ##SDL_endian.h */ + + + + + + + +/* ##SDL_events.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_gamecontroller.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_guid.h */ + + +/* ##SDL_haptic.h */ + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_hints.h */ + + + + + + + + + + + + +/* ##SDL_joystick.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_keyboard.h */ + + + +/* ##SDL_keycode.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_log.h */ + + + + + + + + +/* ##SDL_messagebox.h */ + + +/* ##SDL_mouse.h */ + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_mutex.h */ + + + + + + + + + + + + +/* ##SDL_mutex.h */ + + + + +/* ##SDL_pixels.h */ + + + + + + + + + + + + + +/* ##SDL_rect.h */ + + + + + + + + + + + + + + + + +/* ##SDL_render.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_rwops.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_scancode.h */ + + + + + + + + + + + +/* ##SDL_sensor.h */ + + + + + + + + + + +/* ##SDL_stdinc.h */ + + + + + + + + +/* ##SDL_surface.h */ + + + + + + + + + + + + + + + + + + + + +/* ##SDL_system.h */ + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_thread.h */ + + + + + + +/* ##SDL_timer.h */ + + +/* ##SDL_version.h */ + + + +/* ##SDL_video.h */ + + + + + + + + + + + + + + + + + + + + +/* ##SDL_atomic.h */ + + + + + + + + + + + + +/* ##SDL_audio.h */ + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_cpuinfo.h */ + + + +/* ##SDL_endian.h */ + + + + + + + +/* ##SDL_events.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_gamecontroller.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_guid.h */ + + +/* ##SDL_haptic.h */ + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_hints.h */ + + + + + + + + + + + + +/* ##SDL_joystick.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_keyboard.h */ + + + +/* ##SDL_keycode.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_log.h */ + + + + + + + + +/* ##SDL_messagebox.h */ + + +/* ##SDL_mouse.h */ + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_mutex.h */ + + + + + + + + + + + + +/* ##SDL_mutex.h */ + + + + +/* ##SDL_pixels.h */ + + + + + + + + + + + + + +/* ##SDL_rect.h */ + + + + + + + + + + + + + + + + +/* ##SDL_render.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_rwops.h */ + + + + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_scancode.h */ + + + + + + + + + + + +/* ##SDL_sensor.h */ + + + + + + + + + + +/* ##SDL_stdinc.h */ + + + + + + + + +/* ##SDL_surface.h */ + + + + + + + + + + + + + + + + + + + + +/* ##SDL_system.h */ + + + + + + + + + + + + + + + + + + + + + + + +/* ##SDL_thread.h */ + + + + + + +/* ##SDL_timer.h */ + + +/* ##SDL_version.h */ + + + +/* ##SDL_video.h */ + + + + + + + + + + + + + + + + + + +/* SDL_ENABLE_OLD_NAMES */ + +/* SDL_oldnames_h_ */ \ No newline at end of file diff --git a/src/SDL_openxr.bf b/src/SDL_openxr.bf new file mode 100644 index 0000000..a9b2e03 --- /dev/null +++ b/src/SDL_openxr.bf @@ -0,0 +1,242 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategoryOpenXR + * + * Functions for creating OpenXR handles for SDL_gpu contexts. + * + * For the most part, OpenXR operates independent of SDL, but + * the graphics initialization depends on direct support from SDL_gpu. + * + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + + + +/* OPENXR_H_ */ + + +public const let XR_NULL_HANDLE = 0; + + + +/* XR_DEFINE_HANDLE */ + +[AllowDuplicates] public enum XrStructureType : c_int { + XR_TYPE_SESSION_CREATE_INFO = 8, + XR_TYPE_SWAPCHAIN_CREATE_INFO = 9, +} + +public typealias XrInstance = Uint64; +public typealias XrSystemId = Uint64; +public typealias XrSession = Uint64; +public typealias XrSwapchain = Uint64; + +[CRepr] public struct XrSessionCreateInfo { + public XrStructureType type; + public void* next; +} +[CRepr] public struct XrSwapchainCreateInfo { + public XrStructureType type; + public void* next; +} + +[AllowDuplicates] public enum XrResult : c_int { + XR_ERROR_FUNCTION_UNSUPPORTED = -7, + XR_ERROR_HANDLE_INVALID = -12, +} + +public typealias PFN_xrGetInstanceProcAddr = SDL.FunctionPointer; +/* NO_SDL_OPENXR_TYPEDEFS */ + +/** + * Creates an OpenXR session. + * + * The OpenXR system ID is pulled from the passed GPU context. + * + * \param device a GPU context. + * \param createinfo the create info for the OpenXR session, sans the system + * ID. + * \param session a pointer filled in with an OpenXR session created for the + * given device. + * \returns the result of the call. + * + * \since This function is available since SDL 3.6.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +[LinkName("SDL_CreateGPUXRSession")] public static extern XrResult CreateGPUXRSession(GPUDevice* device, XrSessionCreateInfo* createinfo, out XrSession session); + +/** + * Queries the GPU device for supported XR swapchain image formats. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * \param device a GPU context. + * \param session an OpenXR session created for the given device. + * \param num_formats a pointer filled with the number of supported XR + * swapchain formats. + * \returns a 0 terminated array of supported formats 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.6.0. + * + * \sa SDL_CreateGPUXRSwapchain + */ +[LinkName("SDL_GetGPUXRSwapchainFormats")] public static extern GPUTextureFormat* GetGPUXRSwapchainFormats(GPUDevice* device, XrSession session, c_int* num_formats); + +/** + * Creates an OpenXR swapchain. + * + * The array returned via `textures` is sized according to + * `xrEnumerateSwapchainImages`, and thus should only be accessed via index + * values returned from `xrAcquireSwapchainImage`. + * + * Applications are still allowed to call `xrEnumerateSwapchainImages` on the + * returned XrSwapchain if they need to get the exact size of the array. + * + * \param device a GPU context. + * \param session an OpenXR session created for the given device. + * \param createinfo the create info for the OpenXR swapchain, sans the + * format. + * \param format a supported format for the OpenXR swapchain. + * \param swapchain a pointer filled in with the created OpenXR swapchain. + * \param textures a pointer filled in with the array of created swapchain + * images. + * \returns the result of the call. + * + * \since This function is available since SDL 3.6.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + * \sa SDL_CreateGPUXRSession + * \sa SDL_GetGPUXRSwapchainFormats + * \sa SDL_DestroyGPUXRSwapchain + */ +[LinkName("SDL_CreateGPUXRSwapchain")] public static extern XrResult CreateGPUXRSwapchain(GPUDevice* device, XrSession session, XrSwapchainCreateInfo* createinfo, GPUTextureFormat format, out XrSwapchain swapchain, out GPUTexture** textures); + +/** + * Destroys and OpenXR swapchain previously returned by + * SDL_CreateGPUXRSwapchain. + * + * \param device a GPU context. + * \param swapchain a swapchain previously returned by + * SDL_CreateGPUXRSwapchain. + * \param swapchainImages an array of swapchain images returned by the same + * call to SDL_CreateGPUXRSwapchain. + * \returns the result of the call. + * + * \since This function is available since SDL 3.6.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + * \sa SDL_CreateGPUXRSession + * \sa SDL_CreateGPUXRSwapchain + */ +[LinkName("SDL_DestroyGPUXRSwapchain")] public static extern XrResult DestroyGPUXRSwapchain(GPUDevice* device, XrSwapchain swapchain, GPUTexture** swapchainImages); + +/** + * Dynamically load the OpenXR loader. + * + * This can be called at any time. + * + * SDL keeps a reference count of the OpenXR loader, calling this function + * multiple times will increment that count, rather than loading the library + * multiple times. + * + * If not called, this will be implicitly called when creating a GPU device + * with OpenXR. + * + * This function will use the platform default OpenXR loader name, unless the + * `SDL_HINT_OPENXR_LIBRARY` hint is set. + * + * \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.6.0. + * + * \sa SDL_HINT_OPENXR_LIBRARY + */ +[LinkName("SDL_OpenXR_LoadLibrary")] public static extern bool OpenXR_LoadLibrary(); + +/** + * Unload the OpenXR loader previously loaded by SDL_OpenXR_LoadLibrary. + * + * SDL keeps a reference count of the OpenXR loader, calling this function + * will decrement that count. Once the reference count reaches zero, the + * library is unloaded. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.6.0. + */ +[LinkName("SDL_OpenXR_UnloadLibrary")] public static extern void OpenXR_UnloadLibrary(); + +/** + * Get the address of the `xrGetInstanceProcAddr` function. + * + * This should be called after either calling SDL_OpenXR_LoadLibrary() or + * creating an OpenXR SDL_GPUDevice. + * + * The actual type of the returned function pointer is + * PFN_xrGetInstanceProcAddr, but that isn't always available. You should + * include the OpenXR headers before this header, or cast the return value of + * this function to the correct type. + * + * \returns the function pointer for `xrGetInstanceProcAddr` or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.6.0. + */ +[LinkName("SDL_OpenXR_GetXrGetInstanceProcAddr")] public static extern FunctionPointer OpenXR_GetXrGetInstanceProcAddr(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_openxr_h_ */ \ No newline at end of file diff --git a/src/SDL_pen.bf b/src/SDL_pen.bf new file mode 100644 index 0000000..ce5d202 --- /dev/null +++ b/src/SDL_pen.bf @@ -0,0 +1,209 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias PenID = Uint32; + +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let 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. + */ +public const let 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. + */ +public enum PenInputFlags : Uint32 +{ + Down = (1u << 0), /**< pen is pressed down */ + Button1 = (1u << 1), /**< button 1 is pressed */ + Button2 = (1u << 2), /**< button 2 is pressed */ + Button3 = (1u << 3), /**< button 3 is pressed */ + Button4 = (1u << 4), /**< button 4 is pressed */ + Button5 = (1u << 5), /**< button 5 is pressed */ + EraserTip = (1u << 30), /**< eraser tip is used */ + InProximity = (1u << 31), /**< pen is in proximity (since SDL 3.4.0) */ +} /**< 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. + */ +[AllowDuplicates] public enum PenAxis : c_int +{ + Pressure, /**< Pen pressure. Unidirectional: 0 to 1.0 */ + Xtilt, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + Ytilt, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ + Distance, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ + Rotation, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ + Slider, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ + TangentialPressure, /**< Pressure from squeezing the pen ("barrel pressure"). */ + Count, /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ +} + +/** + * 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. + */ +[AllowDuplicates] public enum PenDeviceType : c_int +{ + Invalid = -1, /**< Not a valid pen device. */ + Unknown, /**< Don't know specifics of this pen. */ + Direct, /**< Pen touches display. */ + Indirect, /**< Pen touches something that isn't the display. */ +} + +/** + * 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. + */ +[LinkName("SDL_GetPenDeviceType")] public static extern PenDeviceType GetPenDeviceType(PenID instance_id); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_pen_h_ */ diff --git a/src/SDL_pixels.bf b/src/SDL_pixels.bf new file mode 100644 index 0000000..6106212 --- /dev/null +++ b/src/SDL_pixels.bf @@ -0,0 +1,1451 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * A fully opaque 8-bit alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT + */ +public const let 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 + */ +public const let 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 + */ +public const let 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 + */ +public const let ALPHA_TRANSPARENT_FLOAT = 0.0f; + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum PixelType : c_int +{ + Unknown, + Index1, + Index4, + Index8, + Packed8, + Packed16, + Packed32, + Arrayu8, + Arrayu16, + Arrayu32, + Arrayf16, + Arrayf32, + /* appended at the end for compatibility with sdl2-compat: */ + Index2, +} + +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum BitmapOrder : c_int +{ + None, + _4321, + _1234, +} + +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum PackedOrder : c_int +{ + None, + Xrgb, + Rgbx, + Argb, + Rgba, + Xbgr, + Bgrx, + Abgr, + Bgra, +} + +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum ArrayOrder : c_int +{ + None, + Rgb, + Rgba, + Argb, + Bgr, + Bgra, + Abgr, +} + +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum PackedLayout : c_int +{ + None, + _332, + _4444, + _1555, + _5551, + _565, + _8888, + _2101010, + _1010102, +} + +/** + * 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. + */ + + +/** + * 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. + */ + + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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 + */ + + + +/** + * 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 + */ + + + + + + + + +/** + * 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. + */ + + + + + + + +/** + * 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. + */ + + + + + + +/** + * 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. + */ + + + + + + + + +/** + * 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. + */ + + + + + +/** + * 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. + */ + + + + + +/** + * 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. + */ + + + + + + + + + + + + + +/** + * 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. + */ +/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ + + +/* 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. + */ +[AllowDuplicates] public enum PixelFormat : c_int +{ + Unknown = 0, + Index1lsb = 0x11100100u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_4321, 0, 1, 0), */ + Index1msb = 0x11200100u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0, 1, 0), */ + Index2lsb = 0x1c100200u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0, 2, 0), */ + Index2msb = 0x1c200200u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0, 2, 0), */ + Index4lsb = 0x12100400u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0, 4, 0), */ + Index4msb = 0x12200400u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_1234, 0, 4, 0), */ + Index8 = 0x13000801u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX8, 0, 0, 8, 1), */ + Rgb332 = 0x14110801u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_332, 8, 1), */ + Xrgb4444 = 0x15120c02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_4444, 12, 2), */ + Xbgr4444 = 0x15520c02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_4444, 12, 2), */ + Xrgb1555 = 0x15130f02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_1555, 15, 2), */ + Xbgr1555 = 0x15530f02u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_1555, 15, 2), */ + Argb4444 = 0x15321002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_4444, 16, 2), */ + Rgba4444 = 0x15421002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_4444, 16, 2), */ + Abgr4444 = 0x15721002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_4444, 16, 2), */ + Bgra4444 = 0x15821002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_4444, 16, 2), */ + Argb1555 = 0x15331002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_1555, 16, 2), */ + Rgba5551 = 0x15441002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_5551, 16, 2), */ + Abgr1555 = 0x15731002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_1555, 16, 2), */ + Bgra5551 = 0x15841002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_5551, 16, 2), */ + Rgb565 = 0x15151002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_565, 16, 2), */ + Bgr565 = 0x15551002u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_565, 16, 2), */ + Rgb24 = 0x17101803u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_RGB, 0, 24, 3), */ + Bgr24 = 0x17401803u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0, 24, 3), */ + Xrgb8888 = 0x16161804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_8888, 24, 4), */ + Rgbx8888 = 0x16261804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX, SDL_PACKEDLAYOUT_8888, 24, 4), */ + Xbgr8888 = 0x16561804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_8888, 24, 4), */ + Bgrx8888 = 0x16661804u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX, SDL_PACKEDLAYOUT_8888, 24, 4), */ + Argb8888 = 0x16362004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_8888, 32, 4), */ + Rgba8888 = 0x16462004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4), */ + Abgr8888 = 0x16762004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_8888, 32, 4), */ + Bgra8888 = 0x16862004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA, SDL_PACKEDLAYOUT_8888, 32, 4), */ + Xrgb2101010 = 0x16172004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + Xbgr2101010 = 0x16572004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + Argb2101010 = 0x16372004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + Abgr2101010 = 0x16772004u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR, SDL_PACKEDLAYOUT_2101010, 32, 4), */ + Rgb48 = 0x18103006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ + Bgr48 = 0x18403006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ + Rgba64 = 0x18204008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ + Argb64 = 0x18304008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ + Bgra64 = 0x18504008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ + Abgr64 = 0x18604008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ + Rgb48Float = 0x1a103006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGB, 0, 48, 6), */ + Bgr48Float = 0x1a403006u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGR, 0, 48, 6), */ + Rgba64Float = 0x1a204008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_RGBA, 0, 64, 8), */ + Argb64Float = 0x1a304008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ARGB, 0, 64, 8), */ + Bgra64Float = 0x1a504008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_BGRA, 0, 64, 8), */ + Abgr64Float = 0x1a604008u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF16, SDL_ARRAYORDER_ABGR, 0, 64, 8), */ + Rgb96Float = 0x1b10600cu, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGB, 0, 96, 12), */ + Bgr96Float = 0x1b40600cu, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGR, 0, 96, 12), */ + Rgba128Float = 0x1b208010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_RGBA, 0, 128, 16), */ + Argb128Float = 0x1b308010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ARGB, 0, 128, 16), */ + Bgra128Float = 0x1b508010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_BGRA, 0, 128, 16), */ + Abgr128Float = 0x1b608010u, + /* SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYF32, SDL_ARRAYORDER_ABGR, 0, 128, 16), */ + + Yv12 = 0x32315659u, /**< Planar mode: Y + V + U (3 planes) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), */ + Iyuv = 0x56555949u, /**< Planar mode: Y + U + V (3 planes) */ + /* SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), */ + Yuy2 = 0x32595559u, /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), */ + Uyvy = 0x59565955u, /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), */ + Yvyu = 0x55595659u, /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ + /* SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U'), */ + Nv12 = 0x3231564eu, /**< Planar mode: Y + U/V interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('N', 'V', '1', '2'), */ + Nv21 = 0x3132564eu, /**< Planar mode: Y + V/U interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ + P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ + /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ + ExternalOes = 0x2053454fu, /**< Android video texture format */ + /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + Mjpg = 0x47504a4du, /**< Motion JPEG */ + /* SDL_DEFINE_PIXELFOURCC('M', 'J', 'P', 'G') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + + Rgba32 = Rgba8888, + Argb32 = Argb8888, + Bgra32 = Bgra8888, + Abgr32 = Abgr8888, + Rgbx32 = Rgbx8888, + Xrgb32 = Xrgb8888, + Bgrx32 = Bgrx8888, + Xbgr32 = Xbgr8888, + + + + + + + + + + +} + +/** + * Colorspace color type. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum ColorType : c_int +{ + Unknown = 0, + Rgb = 1, + Ycbcr = 2, +} + +/** + * 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. + */ +[AllowDuplicates] public enum ColorRange : c_int +{ + Unknown = 0, + Limited = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */ + Full = 2, /**< Full range, e.g. 0-255 for 8-bit RGB and luma, and 1-255 for 8-bit chroma */ +} + +/** + * 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. + */ +[AllowDuplicates] public enum ColorPrimaries : c_int +{ + Unknown = 0, + Bt709 = 1, /**< ITU-R BT.709-6 */ + Unspecified = 2, + Bt470m = 4, /**< ITU-R BT.470-6 System M */ + Bt470bg = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625 */ + Bt601 = 6, /**< ITU-R BT.601-7 525, SMPTE 170M */ + Smpte240 = 7, /**< SMPTE 240M, functionally the same as SDL_COLOR_PRIMARIES_BT601 */ + GenericFilm = 8, /**< Generic film (color filters using Illuminant C) */ + Bt2020 = 9, /**< ITU-R BT.2020-2 / ITU-R BT.2100-0 */ + Xyz = 10, /**< SMPTE ST 428-1 */ + Smpte431 = 11, /**< SMPTE RP 431-2 */ + Smpte432 = 12, /**< SMPTE EG 432-1 / DCI P3 */ + Ebu3213 = 22, /**< EBU Tech. 3213-E */ + Custom = 31, +} + +/** + * 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. + */ +[AllowDuplicates] public enum TransferCharacteristics : c_int +{ + Unknown = 0, + Bt709 = 1, /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */ + Unspecified = 2, + Gamma22 = 4, /**< ITU-R BT.470-6 System M / ITU-R BT1700 625 PAL & SECAM */ + Gamma28 = 5, /**< ITU-R BT.470-6 System B, G */ + Bt601 = 6, /**< SMPTE ST 170M / ITU-R BT.601-7 525 or 625 */ + Smpte240 = 7, /**< SMPTE ST 240M */ + Linear = 8, + Log100 = 9, + Log100Sqrt10 = 10, + Iec61966 = 11, /**< IEC 61966-2-4 */ + Bt1361 = 12, /**< ITU-R BT1361 Extended Colour Gamut */ + Srgb = 13, /**< IEC 61966-2-1 (sRGB or sYCC) */ + Bt202010bit = 14, /**< ITU-R BT2020 for 10-bit system */ + Bt202012bit = 15, /**< ITU-R BT2020 for 12-bit system */ + Pq = 16, /**< SMPTE ST 2084 for 10-, 12-, 14- and 16-bit systems */ + Smpte428 = 17, /**< SMPTE ST 428-1 */ + Hlg = 18, /**< ARIB STD-B67, known as "hybrid log-gamma" (HLG) */ + Custom = 31, +} + +/** + * 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. + */ +[AllowDuplicates] public enum MatrixCoefficients : c_int +{ + Identity = 0, + Bt709 = 1, /**< ITU-R BT.709-6 */ + Unspecified = 2, + Fcc = 4, /**< US FCC Title 47 */ + Bt470bg = 5, /**< ITU-R BT.470-6 System B, G / ITU-R BT.601-7 625, functionally the same as SDL_MATRIX_COEFFICIENTS_BT601 */ + Bt601 = 6, /**< ITU-R BT.601-7 525 */ + Smpte240 = 7, /**< SMPTE 240M */ + Ycgco = 8, + Bt2020Ncl = 9, /**< ITU-R BT.2020-2 non-constant luminance */ + Bt2020Cl = 10, /**< ITU-R BT.2020-2 constant luminance */ + Smpte2085 = 11, /**< SMPTE ST 2085 */ + ChromaDerivedNcl = 12, + ChromaDerivedCl = 13, + Ictcp = 14, /**< ITU-R BT.2100-0 ICTCP */ + Custom = 31, +} + +/** + * Colorspace chroma sample location. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum ChromaLocation : c_int +{ + None = 0, /**< RGB, no chroma sampling */ + 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. */ + 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. */ + 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"). */ +} + + +/* 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. + */ + + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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 + */ +[AllowDuplicates] public enum Colorspace : c_int +{ + Unknown = 0, + + /* sRGB is a gamma corrected colorspace, and the default colorspace for SDL rendering and 8-bit RGB surfaces */ + 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 */ + SrgbLinear = 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 */ + 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), */ + + 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), */ + + Bt601Limited = 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), */ + + Bt601Full = 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), */ + + Bt709Limited = 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), */ + + Bt709Full = 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), */ + + Bt2020Limited = 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), */ + + Bt2020Full = 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), */ + + RgbDefault = Srgb, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + YuvDefault = Bt601Limited, /**< The default colorspace for YUV surfaces if no colorspace is specified */ +} + +/** + * 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. + */ +[CRepr] public struct Color +{ + public Uint8 r; + public Uint8 g; + public Uint8 b; + public Uint8 a; +} + +/** + * 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. + */ +[CRepr] public struct FColor +{ + public float r; + public float g; + public float b; + public float a; +} + +/** + * A set of indexed colors representing a palette. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetPaletteColors + */ +[CRepr] public struct Palette +{ + public c_int ncolors; /**< number of elements in `colors`. */ + public Color* colors; /**< an array of colors, `ncolors` long. */ + public Uint32 version; /**< internal use only, do not touch. */ + public c_int refcount; /**< internal use only, do not touch. */ +} + +/** + * Details about the format of a pixel. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct PixelFormatDetails +{ + public PixelFormat format; + public Uint8 bits_per_pixel; + public Uint8 bytes_per_pixel; + public Uint8[2] padding; + public Uint32 Rmask; + public Uint32 Gmask; + public Uint32 Bmask; + public Uint32 Amask; + public Uint8 Rbits; + public Uint8 Gbits; + public Uint8 Bbits; + public Uint8 Abits; + public Uint8 Rshift; + public Uint8 Gshift; + public Uint8 Bshift; + public Uint8 Ashift; +} + +/** + * 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. + */ +[LinkName("SDL_GetPixelFormatName")] public static extern c_char* GetPixelFormatName(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 + */ +[LinkName("SDL_GetMasksForPixelFormat")] public static extern bool GetMasksForPixelFormat(PixelFormat format, c_int* bpp, out Uint32 Rmask, out Uint32 Gmask, out Uint32 Bmask, out 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 + */ +[LinkName("SDL_GetPixelFormatForMasks")] public static extern PixelFormat GetPixelFormatForMasks(c_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. + */ +[LinkName("SDL_GetPixelFormatDetails")] public static extern PixelFormatDetails* GetPixelFormatDetails(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 + */ +[LinkName("SDL_CreatePalette")] public static extern Palette* CreatePalette(c_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. + */ +[LinkName("SDL_SetPaletteColors")] public static extern bool SetPaletteColors(Palette* palette, Color* colors, c_int firstcolor, c_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 + */ +[LinkName("SDL_DestroyPalette")] public static extern void DestroyPalette(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 + */ +[LinkName("SDL_MapRGB")] public static extern Uint32 MapRGB(PixelFormatDetails* format, 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 + */ +[LinkName("SDL_MapRGBA")] public static extern Uint32 MapRGBA(PixelFormatDetails* format, 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 + */ +[LinkName("SDL_GetRGB")] public static extern void GetRGB(Uint32 pixelvalue, PixelFormatDetails* format, Palette* palette, out Uint8 r, out Uint8 g, out 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 + */ +[LinkName("SDL_GetRGBA")] public static extern void GetRGBA(Uint32 pixelvalue, PixelFormatDetails* format, Palette* palette, out Uint8 r, out Uint8 g, out Uint8 b, out Uint8 a); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_pixels_h_ */ \ No newline at end of file diff --git a/src/SDL_platform.bf b/src/SDL_platform.bf new file mode 100644 index 0000000..ba7850e --- /dev/null +++ b/src/SDL_platform.bf @@ -0,0 +1,75 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 + * + * SDL provides a means to identify the app's platform, both at compile time + * and runtime. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * Get the name of the platform. + * + * Here are the names returned for some (but not all) supported platforms: + * + * - "Windows" + * - "macOS" + * - "Linux" + * - "iOS" + * - "Android" + * + * \returns the name of the platform. If the correct platform name is not + * available, returns a string beginning with the text "Unknown". + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetPlatform")] public static extern c_char* GetPlatform(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_platform_h_ */ \ No newline at end of file diff --git a/src/SDL_platform_defines.bf b/src/SDL_platform_defines.bf new file mode 100644 index 0000000..3905551 --- /dev/null +++ b/src/SDL_platform_defines.bf @@ -0,0 +1,505 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +/* + 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. + */ + + + + + + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * 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. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + + +/** + * 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. + */ + + + + + +/** + * 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 + */ + + +/* lets us know what version of macOS we're compiling on */ + +/* Older compilers don't support this */ + + + + + + + +/* 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 +*/ + + + + + + + + + + + + + + + + + + + + + +/** + * 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 + */ + + + + + +/** + * 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 + */ + + + + + +/** + * 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 + */ + + + + +/** + * 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 + */ + + + + +/* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ +/* TARGET_OS_IPHONE */ +/* defined(__APPLE__) */ + + + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * 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 + */ + + +/* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ + + + + + + + + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ +/* _MSC_VER == 1700 for Visual Studio 2012 */ + + + + + + + + + + +/* HAVE_WINAPIFAMILY_H */ + + + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + + + + + + + +/* 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. + */ + + + + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + +/** + * 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. + */ + + + +/* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + + +/* This is to support generic "any GDK" separate from a platform-specific GDK */ + + +/** + * 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. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for the Nokia + * N-Gage. + * + * \since This macro is available since SDL 3.4.0. + */ + + + + + +/** + * A preprocessor macro that is only defined if compiling for GNU/Hurd. + * + * \since This macro is available since SDL 3.4.0. + */ + + + +/* SDL_platform_defines_h_ */ \ No newline at end of file diff --git a/src/SDL_power.bf b/src/SDL_power.bf new file mode 100644 index 0000000..bdf7889 --- /dev/null +++ b/src/SDL_power.bf @@ -0,0 +1,117 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + + + + +/** + * # CategoryPower + * + * 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. + */ + + + + + +/* Set up for C function definitions, even when using 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. + */ +[AllowDuplicates] public enum PowerState : c_int +{ + Error = -1, /**< error determining power status */ + Unknown, /**< cannot determine power status */ + OnBattery, /**< Not plugged in, running on the battery */ + NoBattery, /**< Plugged in, no battery available */ + Charging, /**< Plugged in, charging battery */ + Charged, /**< Plugged in, battery charged */ +} + +/** + * Get the current power supply details. + * + * 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. + * + * Battery status can change at any time; if you are concerned with power + * state, you should call this function frequently, and perhaps ignore changes + * until they seem to be stable for a few seconds. + * + * It's possible a platform can only report battery percentage or time left + * but not both. + * + * On some platforms, retrieving power supply details might be expensive. If + * you want to display continuous status you could call this function every + * minute or so. + * + * \param seconds a pointer filled in with the seconds of battery life left, + * or NULL to ignore. This will be filled in with -1 if we + * can't determine a value or there is no battery. + * \param percent a pointer filled in with the percentage of battery life + * left, between 0 and 100, or NULL to ignore. This will be + * filled in with -1 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. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetPowerInfo")] public static extern PowerState GetPowerInfo(out c_int seconds, out c_int percent); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_power_h_ */ \ No newline at end of file diff --git a/src/SDL_process.bf b/src/SDL_process.bf new file mode 100644 index 0000000..8b95caa --- /dev/null +++ b/src/SDL_process.bf @@ -0,0 +1,452 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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! + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_CreateProcess")] public static extern Process* CreateProcess(c_char** 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 + */ +[AllowDuplicates] public enum ProcessIO : c_int +{ + StdioInherited, /**< The I/O stream is inherited from the application. */ + StdioNull, /**< The I/O stream is ignored. */ + StdioApp, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + StdioRedirect, /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} + +/** + * 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 + */ +[LinkName("SDL_CreateProcessWithProperties")] public static extern Process* CreateProcessWithProperties(PropertiesID props); + +public const let PROP_PROCESS_CREATE_ARGS_POINTER = "SDL.process.create.args"; +public const let PROP_PROCESS_CREATE_ENVIRONMENT_POINTER = "SDL.process.create.environment"; +public const let PROP_PROCESS_CREATE_WORKING_DIRECTORY_STRING = "SDL.process.create.working_directory"; +public const let PROP_PROCESS_CREATE_STDIN_NUMBER = "SDL.process.create.stdin_option"; +public const let PROP_PROCESS_CREATE_STDIN_POINTER = "SDL.process.create.stdin_source"; +public const let PROP_PROCESS_CREATE_STDOUT_NUMBER = "SDL.process.create.stdout_option"; +public const let PROP_PROCESS_CREATE_STDOUT_POINTER = "SDL.process.create.stdout_source"; +public const let PROP_PROCESS_CREATE_STDERR_NUMBER = "SDL.process.create.stderr_option"; +public const let PROP_PROCESS_CREATE_STDERR_POINTER = "SDL.process.create.stderr_source"; +public const let PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN = "SDL.process.create.stderr_to_stdout"; +public const let PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN = "SDL.process.create.background"; +public const let 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 + */ +[LinkName("SDL_GetProcessProperties")] public static extern PropertiesID GetProcessProperties(Process* process); + +public const let PROP_PROCESS_PID_NUMBER = "SDL.process.pid"; +public const let PROP_PROCESS_STDIN_POINTER = "SDL.process.stdin"; +public const let PROP_PROCESS_STDOUT_POINTER = "SDL.process.stdout"; +public const let PROP_PROCESS_STDERR_POINTER = "SDL.process.stderr"; +public const let 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 + */ +[LinkName("SDL_ReadProcess")] public static extern void* ReadProcess(Process* process, out c_size datasize, out c_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 + */ +[LinkName("SDL_GetProcessInput")] public static extern IOStream* GetProcessInput(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 + */ +[LinkName("SDL_GetProcessOutput")] public static extern IOStream* GetProcessOutput(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 + */ +[LinkName("SDL_KillProcess")] public static extern bool KillProcess(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 + */ +[LinkName("SDL_WaitProcess")] public static extern bool WaitProcess(Process* process, bool block, out c_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 + */ +[LinkName("SDL_DestroyProcess")] public static extern void DestroyProcess(Process* process); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_process_h_ */ \ No newline at end of file diff --git a/src/SDL_properties.bf b/src/SDL_properties.bf new file mode 100644 index 0000000..2047da6 --- /dev/null +++ b/src/SDL_properties.bf @@ -0,0 +1,581 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * An ID that represents a properties set. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias PropertiesID = Uint32; + +/** + * SDL property type + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum PropertyType : c_int +{ + Invalid, + Pointer, + String, + Number, + Float, + Boolean, +} + +/** + * 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. + */ +public const let 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. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetGlobalProperties")] public static extern PropertiesID GetGlobalProperties(); + +/** + * 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 + */ +[LinkName("SDL_CreateProperties")] public static extern PropertiesID CreateProperties(); + +/** + * 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. + */ +[LinkName("SDL_CopyProperties")] public static extern bool CopyProperties(PropertiesID src, 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 + */ +[LinkName("SDL_LockProperties")] public static extern bool LockProperties(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 + */ +[LinkName("SDL_UnlockProperties")] public static extern void UnlockProperties(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 + */ +public function void 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 + */ +[LinkName("SDL_SetPointerPropertyWithCleanup")] public static extern bool SetPointerPropertyWithCleanup(PropertiesID props, c_char* name, void* value, 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 + */ +[LinkName("SDL_SetPointerProperty")] public static extern bool SetPointerProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_SetStringProperty")] public static extern bool SetStringProperty(PropertiesID props, c_char* name, c_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 + */ +[LinkName("SDL_SetNumberProperty")] public static extern bool SetNumberProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_SetFloatProperty")] public static extern bool SetFloatProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_SetBooleanProperty")] public static extern bool SetBooleanProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_HasProperty")] public static extern bool HasProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_GetPropertyType")] public static extern PropertyType GetPropertyType(PropertiesID props, c_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 + */ +[LinkName("SDL_GetPointerProperty")] public static extern void* GetPointerProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_GetStringProperty")] public static extern c_char* GetStringProperty(PropertiesID props, c_char* name, c_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 + */ +[LinkName("SDL_GetNumberProperty")] public static extern Sint64 GetNumberProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_GetFloatProperty")] public static extern float GetFloatProperty(PropertiesID props, c_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 + */ +[LinkName("SDL_GetBooleanProperty")] public static extern bool GetBooleanProperty(PropertiesID props, c_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. + */ +[LinkName("SDL_ClearProperty")] public static extern bool ClearProperty(PropertiesID props, c_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 + */ +public function void EnumeratePropertiesCallback(void* userdata, PropertiesID props, c_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. + */ +[LinkName("SDL_EnumerateProperties")] public static extern bool EnumerateProperties(PropertiesID props, 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 + */ +[LinkName("SDL_DestroyProperties")] public static extern void DestroyProperties(PropertiesID props); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_properties_h_ */ \ No newline at end of file diff --git a/src/SDL_rect.bf b/src/SDL_rect.bf new file mode 100644 index 0000000..68c1e50 --- /dev/null +++ b/src/SDL_rect.bf @@ -0,0 +1,521 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * The structure that defines a point (using integers). + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetRectEnclosingPoints + * \sa SDL_PointInRect + */ +[CRepr] public struct Point +{ + public c_int x; + public c_int y; +} + +/** + * 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 + */ +[CRepr] public struct FPoint +{ + public float x; + public float y; +} + + +/** + * 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 + */ +[CRepr] public struct Rect +{ + public c_int x; public c_int y; + public c_int w; public c_int h; +} + + +/** + * 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 + */ +[CRepr] public struct FRect +{ + public float x; + public float y; + public float w; + public float h; +} + + +/** + * 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. + */ +[LinkName("SDL_RectToFRect")] public static extern void RectToFRect(Rect* rect, out FRect frect); + + + + + + + +/** + * 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. + */ +[LinkName("SDL_PointInRect")] public static extern bool PointInRect(Point* p, Rect* r); + + + + + +/** + * 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. + */ +[LinkName("SDL_RectEmpty")] public static extern bool RectEmpty(Rect* r); + + + + +/** + * 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. + */ +[LinkName("SDL_RectsEqual")] public static extern bool RectsEqual(Rect* a, Rect* b); + + + + + +/** + * 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 + */ +[LinkName("SDL_HasRectIntersection")] public static extern bool HasRectIntersection(Rect* A, Rect* B); + +/** + * Calculate the intersection of two rectangles. + * + * If `result` is NULL then this function will return false. + * + * \param A an SDL_Rect structure representing the first rectangle. + * \param B an SDL_Rect structure representing the second rectangle. + * \param result an SDL_Rect structure filled in with the intersection of + * rectangles `A` and `B`. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasRectIntersection + */ +[LinkName("SDL_GetRectIntersection")] public static extern bool GetRectIntersection(Rect* A, Rect* B, Rect* result); + +/** + * Calculate the union of two rectangles. + * + * \param A an SDL_Rect structure representing the first rectangle. + * \param B an SDL_Rect structure representing the second rectangle. + * \param result an SDL_Rect structure filled in with the union of rectangles + * `A` and `B`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectUnion")] public static extern bool GetRectUnion(Rect* A, Rect* B, Rect* result); + +/** + * Calculate a minimal rectangle enclosing a set of points. + * + * If `clip` is not NULL then only points inside of the clipping rectangle are + * considered. + * + * \param points an array of SDL_Point structures representing points to be + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_Rect used for clipping or NULL to enclose all points. + * \param result an SDL_Rect structure filled in with the minimal enclosing + * rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectEnclosingPoints")] public static extern bool GetRectEnclosingPoints(Point* points, c_int count, Rect* clip, Rect* result); + +/** + * Calculate the intersection of a rectangle and line segment. + * + * This function is used to clip a line segment to a rectangle. A line segment + * contained entirely within the rectangle or that does not intersect will + * remain unchanged. A line segment that crosses the rectangle at either or + * both ends will be clipped to the boundary of the rectangle and the new + * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. + * + * \param rect an SDL_Rect structure representing the rectangle to intersect. + * \param X1 a pointer to the starting X-coordinate of the line. + * \param Y1 a pointer to the starting Y-coordinate of the line. + * \param X2 a pointer to the ending X-coordinate of the line. + * \param Y2 a pointer to the ending Y-coordinate of the line. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectAndLineIntersection")] public static extern bool GetRectAndLineIntersection(Rect* rect, c_int* X1, c_int* Y1, c_int* X2, c_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. + */ +[LinkName("SDL_PointInRectFloat")] public static extern bool PointInRectFloat(FPoint* p, FRect* r); + + + + + +/** + * 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. + */ +[LinkName("SDL_RectEmptyFloat")] public static extern bool RectEmptyFloat(FRect* r); + + + + +/** + * 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 + */ +[LinkName("SDL_RectsEqualEpsilon")] public static extern bool RectsEqualEpsilon(FRect* a, FRect* b, float epsilon); + + + + + + + + + +/** + * 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 + */ +[LinkName("SDL_RectsEqualFloat")] public static extern bool RectsEqualFloat(FRect* a, FRect* b); + + + + +/** + * Determine whether two rectangles intersect with float precision. + * + * If either pointer is NULL the function will return false. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRectIntersectionFloat + */ +[LinkName("SDL_HasRectIntersectionFloat")] public static extern bool HasRectIntersectionFloat(FRect* A, FRect* B); + +/** + * Calculate the intersection of two rectangles with float precision. + * + * If `result` is NULL then this function will return false. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \param result an SDL_FRect structure filled in with the intersection of + * rectangles `A` and `B`. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasRectIntersectionFloat + */ +[LinkName("SDL_GetRectIntersectionFloat")] public static extern bool GetRectIntersectionFloat(FRect* A, FRect* B, FRect* result); + +/** + * Calculate the union of two rectangles with float precision. + * + * \param A an SDL_FRect structure representing the first rectangle. + * \param B an SDL_FRect structure representing the second rectangle. + * \param result an SDL_FRect structure filled in with the union of rectangles + * `A` and `B`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectUnionFloat")] public static extern bool GetRectUnionFloat(FRect* A, FRect* B, FRect* result); + +/** + * Calculate a minimal rectangle enclosing a set of points with float + * precision. + * + * If `clip` is not NULL then only points inside of the clipping rectangle are + * considered. + * + * \param points an array of SDL_FPoint structures representing points to be + * enclosed. + * \param count the number of structures in the `points` array. + * \param clip an SDL_FRect used for clipping or NULL to enclose all points. + * \param result an SDL_FRect structure filled in with the minimal enclosing + * rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectEnclosingPointsFloat")] public static extern bool GetRectEnclosingPointsFloat(FPoint* points, c_int count, FRect* clip, FRect* result); + +/** + * Calculate the intersection of a rectangle and line segment with float + * precision. + * + * This function is used to clip a line segment to a rectangle. A line segment + * contained entirely within the rectangle or that does not intersect will + * remain unchanged. A line segment that crosses the rectangle at either or + * both ends will be clipped to the boundary of the rectangle and the new + * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary. + * + * \param rect an SDL_FRect structure representing the rectangle to intersect. + * \param X1 a pointer to the starting X-coordinate of the line. + * \param Y1 a pointer to the starting Y-coordinate of the line. + * \param X2 a pointer to the ending X-coordinate of the line. + * \param Y2 a pointer to the ending Y-coordinate of the line. + * \returns true if there is an intersection, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetRectAndLineIntersectionFloat")] public static extern bool GetRectAndLineIntersectionFloat(FRect* rect, float* X1, float* Y1, float* X2, float* Y2); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_rect_h_ */ \ No newline at end of file diff --git a/src/SDL_render.bf b/src/SDL_render.bf new file mode 100644 index 0000000..544cb95 --- /dev/null +++ b/src/SDL_render.bf @@ -0,0 +1,3014 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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 + */ + + + + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * The name of the software renderer. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let SOFTWARE_RENDERER = "software"; + +/** + * The name of the GPU renderer. + * + * \since This macro is available since SDL 3.4.0. + */ +public const let GPU_RENDERER = "gpu"; + +/** + * Vertex structure. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct Vertex +{ + public FPoint position; /**< Vertex position, in SDL_Renderer coordinates */ + public FColor color; /**< Vertex color */ + public FPoint tex_coord; /**< Normalized texture coordinates, if needed */ +} + +/** + * The access pattern allowed for a texture. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum TextureAccess : c_int +{ + Static, /**< Changes rarely, not lockable */ + Streaming, /**< Changes frequently, lockable */ + Target, /**< Texture can be used as a render target */ +} + +/** + * 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. + */ +[AllowDuplicates] public enum TextureAddressMode : c_int +{ + Invalid = -1, + Auto, /**< Wrapping is enabled if texture coordinates are outside [0, 1], this is the default */ + Clamp, /**< Texture coordinates are clamped to the [0, 1] range */ + Wrap, /**< The texture is repeated (tiled) */ +} + +/** + * How the logical size is mapped to the output. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum RendererLogicalPresentation : c_int +{ + Disabled, /**< There is no logical size in effect */ + Stretch, /**< The rendered content is stretched to the output resolution */ + Letterbox, /**< The rendered content is fit to the largest dimension and the other dimension is letterboxed with the clear color */ + Overscan, /**< The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds */ + IntegerScale, /**< The rendered content is scaled up by integer multiples to fit the output resolution */ +} + +/** + * A structure representing rendering state + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct Renderer; + + + +/** + * 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 + */ +[CRepr] public struct Texture +{ + public PixelFormat format; /**< The format of the texture, read-only */ + public c_int w; /**< The width of the texture, read-only. */ + public c_int h; /**< The height of the texture, read-only. */ + + public c_int refcount; /**< Application reference count, used when freeing texture */ +} +/* !SDL_INTERNAL */ + + + +/* 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 + */ +[LinkName("SDL_GetNumRenderDrivers")] public static extern c_int GetNumRenderDrivers(); + +/** + * 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 + */ +[LinkName("SDL_GetRenderDriver")] public static extern c_char* GetRenderDriver(c_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 + */ +[LinkName("SDL_CreateWindowAndRenderer")] public static extern bool CreateWindowAndRenderer(c_char* title, c_int width, c_int height, WindowFlags window_flags, Window** window, 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 + */ +[LinkName("SDL_CreateRenderer")] public static extern Renderer* CreateRenderer(Window* window, c_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 + */ +[LinkName("SDL_CreateRendererWithProperties")] public static extern Renderer* CreateRendererWithProperties(PropertiesID props); + +public const let PROP_RENDERER_CREATE_NAME_STRING = "SDL.renderer.create.name"; +public const let PROP_RENDERER_CREATE_WINDOW_POINTER = "SDL.renderer.create.window"; +public const let PROP_RENDERER_CREATE_SURFACE_POINTER = "SDL.renderer.create.surface"; +public const let PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER = "SDL.renderer.create.output_colorspace"; +public const let PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER = "SDL.renderer.create.present_vsync"; +public const let PROP_RENDERER_CREATE_GPU_DEVICE_POINTER = "SDL.renderer.create.gpu.device"; +public const let PROP_RENDERER_CREATE_GPU_SHADERS_SPIRV_BOOLEAN = "SDL.renderer.create.gpu.shaders_spirv"; +public const let PROP_RENDERER_CREATE_GPU_SHADERS_DXIL_BOOLEAN = "SDL.renderer.create.gpu.shaders_dxil"; +public const let PROP_RENDERER_CREATE_GPU_SHADERS_MSL_BOOLEAN = "SDL.renderer.create.gpu.shaders_msl"; +public const let PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER = "SDL.renderer.create.vulkan.instance"; +public const let PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER = "SDL.renderer.create.vulkan.surface"; +public const let PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER = "SDL.renderer.create.vulkan.physical_device"; +public const let PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER = "SDL.renderer.create.vulkan.device"; +public const let PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER = "SDL.renderer.create.vulkan.graphics_queue_family_index"; +public const let 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 + */ +[LinkName("SDL_CreateGPURenderer")] public static extern Renderer* CreateGPURenderer(GPUDevice* device, 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. + */ +[LinkName("SDL_GetGPURendererDevice")] public static extern GPUDevice* GetGPURendererDevice(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 + */ +[LinkName("SDL_CreateSoftwareRenderer")] public static extern Renderer* CreateSoftwareRenderer(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. + */ +[LinkName("SDL_GetRenderer")] public static extern Renderer* GetRenderer(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. + */ +[LinkName("SDL_GetRenderWindow")] public static extern Window* GetRenderWindow(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 + */ +[LinkName("SDL_GetRendererName")] public static extern c_char* GetRendererName(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. + */ +[LinkName("SDL_GetRendererProperties")] public static extern PropertiesID GetRendererProperties(Renderer* renderer); + +public const let PROP_RENDERER_NAME_STRING = "SDL.renderer.name"; +public const let PROP_RENDERER_WINDOW_POINTER = "SDL.renderer.window"; +public const let PROP_RENDERER_SURFACE_POINTER = "SDL.renderer.surface"; +public const let PROP_RENDERER_VSYNC_NUMBER = "SDL.renderer.vsync"; +public const let PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER = "SDL.renderer.max_texture_size"; +public const let PROP_RENDERER_TEXTURE_FORMATS_POINTER = "SDL.renderer.texture_formats"; +public const let PROP_RENDERER_TEXTURE_WRAPPING_BOOLEAN = "SDL.renderer.texture_wrapping"; +public const let PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER = "SDL.renderer.output_colorspace"; +public const let PROP_RENDERER_HDR_ENABLED_BOOLEAN = "SDL.renderer.HDR_enabled"; +public const let PROP_RENDERER_SDR_WHITE_POINT_FLOAT = "SDL.renderer.SDR_white_point"; +public const let PROP_RENDERER_HDR_HEADROOM_FLOAT = "SDL.renderer.HDR_headroom"; +public const let PROP_RENDERER_D3D9_DEVICE_POINTER = "SDL.renderer.d3d9.device"; +public const let PROP_RENDERER_D3D11_DEVICE_POINTER = "SDL.renderer.d3d11.device"; +public const let PROP_RENDERER_D3D11_SWAPCHAIN_POINTER = "SDL.renderer.d3d11.swap_chain"; +public const let PROP_RENDERER_D3D12_DEVICE_POINTER = "SDL.renderer.d3d12.device"; +public const let PROP_RENDERER_D3D12_SWAPCHAIN_POINTER = "SDL.renderer.d3d12.swap_chain"; +public const let PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER = "SDL.renderer.d3d12.command_queue"; +public const let PROP_RENDERER_VULKAN_INSTANCE_POINTER = "SDL.renderer.vulkan.instance"; +public const let PROP_RENDERER_VULKAN_SURFACE_NUMBER = "SDL.renderer.vulkan.surface"; +public const let PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER = "SDL.renderer.vulkan.physical_device"; +public const let PROP_RENDERER_VULKAN_DEVICE_POINTER = "SDL.renderer.vulkan.device"; +public const let PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER = "SDL.renderer.vulkan.graphics_queue_family_index"; +public const let PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER = "SDL.renderer.vulkan.present_queue_family_index"; +public const let PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER = "SDL.renderer.vulkan.swapchain_image_count"; +public const let 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 + */ +[LinkName("SDL_GetRenderOutputSize")] public static extern bool GetRenderOutputSize(Renderer* renderer, out c_int w, out c_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 + */ +[LinkName("SDL_GetCurrentRenderOutputSize")] public static extern bool GetCurrentRenderOutputSize(Renderer* renderer, out c_int w, out c_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 + */ +[LinkName("SDL_CreateTexture")] public static extern Texture* CreateTexture(Renderer* renderer, PixelFormat format, TextureAccess access, c_int w, c_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 + */ +[LinkName("SDL_CreateTextureFromSurface")] public static extern Texture* CreateTextureFromSurface(Renderer* renderer, 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_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 + */ +[LinkName("SDL_CreateTextureWithProperties")] public static extern Texture* CreateTextureWithProperties(Renderer* renderer, PropertiesID props); + +public const let PROP_TEXTURE_CREATE_COLORSPACE_NUMBER = "SDL.texture.create.colorspace"; +public const let PROP_TEXTURE_CREATE_FORMAT_NUMBER = "SDL.texture.create.format"; +public const let PROP_TEXTURE_CREATE_ACCESS_NUMBER = "SDL.texture.create.access"; +public const let PROP_TEXTURE_CREATE_WIDTH_NUMBER = "SDL.texture.create.width"; +public const let PROP_TEXTURE_CREATE_HEIGHT_NUMBER = "SDL.texture.create.height"; +public const let PROP_TEXTURE_CREATE_PALETTE_POINTER = "SDL.texture.create.palette"; +public const let PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT = "SDL.texture.create.SDR_white_point"; +public const let PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT = "SDL.texture.create.HDR_headroom"; +public const let PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER = "SDL.texture.create.d3d11.texture"; +public const let PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER = "SDL.texture.create.d3d11.texture_u"; +public const let PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER = "SDL.texture.create.d3d11.texture_v"; +public const let PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER = "SDL.texture.create.d3d12.texture"; +public const let PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER = "SDL.texture.create.d3d12.texture_u"; +public const let PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER = "SDL.texture.create.d3d12.texture_v"; +public const let PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER = "SDL.texture.create.metal.pixelbuffer"; +public const let PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER = "SDL.texture.create.opengl.texture"; +public const let PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER = "SDL.texture.create.opengl.texture_uv"; +public const let PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER = "SDL.texture.create.opengl.texture_u"; +public const let PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER = "SDL.texture.create.opengl.texture_v"; +public const let PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER = "SDL.texture.create.opengles2.texture"; +public const let PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER = "SDL.texture.create.opengles2.texture_uv"; +public const let PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER = "SDL.texture.create.opengles2.texture_u"; +public const let PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER = "SDL.texture.create.opengles2.texture_v"; +public const let PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER = "SDL.texture.create.vulkan.texture"; +public const let PROP_TEXTURE_CREATE_VULKAN_LAYOUT_NUMBER = "SDL.texture.create.vulkan.layout"; +public const let PROP_TEXTURE_CREATE_GPU_TEXTURE_POINTER = "SDL.texture.create.gpu.texture"; +public const let PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_POINTER = "SDL.texture.create.gpu.texture_uv"; +public const let PROP_TEXTURE_CREATE_GPU_TEXTURE_U_POINTER = "SDL.texture.create.gpu.texture_u"; +public const let 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. + */ +[LinkName("SDL_GetTextureProperties")] public static extern PropertiesID GetTextureProperties(Texture* texture); + +public const let PROP_TEXTURE_COLORSPACE_NUMBER = "SDL.texture.colorspace"; +public const let PROP_TEXTURE_FORMAT_NUMBER = "SDL.texture.format"; +public const let PROP_TEXTURE_ACCESS_NUMBER = "SDL.texture.access"; +public const let PROP_TEXTURE_WIDTH_NUMBER = "SDL.texture.width"; +public const let PROP_TEXTURE_HEIGHT_NUMBER = "SDL.texture.height"; +public const let PROP_TEXTURE_SDR_WHITE_POINT_FLOAT = "SDL.texture.SDR_white_point"; +public const let PROP_TEXTURE_HDR_HEADROOM_FLOAT = "SDL.texture.HDR_headroom"; +public const let PROP_TEXTURE_D3D11_TEXTURE_POINTER = "SDL.texture.d3d11.texture"; +public const let PROP_TEXTURE_D3D11_TEXTURE_U_POINTER = "SDL.texture.d3d11.texture_u"; +public const let PROP_TEXTURE_D3D11_TEXTURE_V_POINTER = "SDL.texture.d3d11.texture_v"; +public const let PROP_TEXTURE_D3D12_TEXTURE_POINTER = "SDL.texture.d3d12.texture"; +public const let PROP_TEXTURE_D3D12_TEXTURE_U_POINTER = "SDL.texture.d3d12.texture_u"; +public const let PROP_TEXTURE_D3D12_TEXTURE_V_POINTER = "SDL.texture.d3d12.texture_v"; +public const let PROP_TEXTURE_OPENGL_TEXTURE_NUMBER = "SDL.texture.opengl.texture"; +public const let PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER = "SDL.texture.opengl.texture_uv"; +public const let PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER = "SDL.texture.opengl.texture_u"; +public const let PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER = "SDL.texture.opengl.texture_v"; +public const let PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER = "SDL.texture.opengl.target"; +public const let PROP_TEXTURE_OPENGL_TEX_W_FLOAT = "SDL.texture.opengl.tex_w"; +public const let PROP_TEXTURE_OPENGL_TEX_H_FLOAT = "SDL.texture.opengl.tex_h"; +public const let PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER = "SDL.texture.opengles2.texture"; +public const let PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER = "SDL.texture.opengles2.texture_uv"; +public const let PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER = "SDL.texture.opengles2.texture_u"; +public const let PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER = "SDL.texture.opengles2.texture_v"; +public const let PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER = "SDL.texture.opengles2.target"; +public const let PROP_TEXTURE_VULKAN_TEXTURE_NUMBER = "SDL.texture.vulkan.texture"; +public const let PROP_TEXTURE_GPU_TEXTURE_POINTER = "SDL.texture.gpu.texture"; +public const let PROP_TEXTURE_GPU_TEXTURE_UV_POINTER = "SDL.texture.gpu.texture_uv"; +public const let PROP_TEXTURE_GPU_TEXTURE_U_POINTER = "SDL.texture.gpu.texture_u"; +public const let 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. + */ +[LinkName("SDL_GetRendererFromTexture")] public static extern Renderer* GetRendererFromTexture(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. + */ +[LinkName("SDL_GetTextureSize")] public static extern bool GetTextureSize(Texture* texture, out float w, out 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 + */ +[LinkName("SDL_SetTexturePalette")] public static extern bool SetTexturePalette(Texture* texture, 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 + */ +[LinkName("SDL_GetTexturePalette")] public static extern Palette* GetTexturePalette(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 + */ +[LinkName("SDL_SetTextureColorMod")] public static extern bool SetTextureColorMod(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 + */ +[LinkName("SDL_SetTextureColorModFloat")] public static extern bool SetTextureColorModFloat(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 + */ +[LinkName("SDL_GetTextureColorMod")] public static extern bool GetTextureColorMod(Texture* texture, out Uint8 r, out Uint8 g, out 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 + */ +[LinkName("SDL_GetTextureColorModFloat")] public static extern bool GetTextureColorModFloat(Texture* texture, out float r, out float g, out 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 + */ +[LinkName("SDL_SetTextureAlphaMod")] public static extern bool SetTextureAlphaMod(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 + */ +[LinkName("SDL_SetTextureAlphaModFloat")] public static extern bool SetTextureAlphaModFloat(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 + */ +[LinkName("SDL_GetTextureAlphaMod")] public static extern bool GetTextureAlphaMod(Texture* texture, out 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 + */ +[LinkName("SDL_GetTextureAlphaModFloat")] public static extern bool GetTextureAlphaModFloat(Texture* texture, out 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 + */ +[LinkName("SDL_SetTextureBlendMode")] public static extern bool SetTextureBlendMode(Texture* texture, 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 + */ +[LinkName("SDL_GetTextureBlendMode")] public static extern bool GetTextureBlendMode(Texture* texture, out 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 + */ +[LinkName("SDL_SetTextureScaleMode")] public static extern bool SetTextureScaleMode(Texture* texture, 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 + */ +[LinkName("SDL_GetTextureScaleMode")] public static extern bool GetTextureScaleMode(Texture* texture, out 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 + */ +[LinkName("SDL_UpdateTexture")] public static extern bool UpdateTexture(Texture* texture, Rect* rect, void* pixels, c_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 + */ +[LinkName("SDL_UpdateYUVTexture")] public static extern bool UpdateYUVTexture(Texture* texture, Rect* rect, Uint8* Yplane, c_int Ypitch, Uint8* Uplane, c_int Upitch, Uint8* Vplane, c_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 + */ +[LinkName("SDL_UpdateNVTexture")] public static extern bool UpdateNVTexture(Texture* texture, Rect* rect, Uint8* Yplane, c_int Ypitch, Uint8* UVplane, c_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 + */ +[LinkName("SDL_LockTexture")] public static extern bool LockTexture(Texture* texture, Rect* rect, void** pixels, c_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 + */ +[LinkName("SDL_LockTextureToSurface")] public static extern bool LockTextureToSurface(Texture* texture, Rect* rect, 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 + */ +[LinkName("SDL_UnlockTexture")] public static extern void UnlockTexture(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 + */ +[LinkName("SDL_SetRenderTarget")] public static extern bool SetRenderTarget(Renderer* renderer, 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 + */ +[LinkName("SDL_GetRenderTarget")] public static extern Texture* GetRenderTarget(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 + */ +[LinkName("SDL_SetRenderLogicalPresentation")] public static extern bool SetRenderLogicalPresentation(Renderer* renderer, c_int w, c_int h, 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 + */ +[LinkName("SDL_GetRenderLogicalPresentation")] public static extern bool GetRenderLogicalPresentation(Renderer* renderer, c_int* w, c_int* h, 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 + */ +[LinkName("SDL_GetRenderLogicalPresentationRect")] public static extern bool GetRenderLogicalPresentationRect(Renderer* renderer, out 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 + */ +[LinkName("SDL_RenderCoordinatesFromWindow")] public static extern bool RenderCoordinatesFromWindow(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 + */ +[LinkName("SDL_RenderCoordinatesToWindow")] public static extern bool RenderCoordinatesToWindow(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 + */ +[LinkName("SDL_ConvertEventToRenderCoordinates")] public static extern bool ConvertEventToRenderCoordinates(Renderer* renderer, 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 + */ +[LinkName("SDL_SetRenderViewport")] public static extern bool SetRenderViewport(Renderer* renderer, 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 + */ +[LinkName("SDL_GetRenderViewport")] public static extern bool GetRenderViewport(Renderer* renderer, 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 + */ +[LinkName("SDL_RenderViewportSet")] public static extern bool RenderViewportSet(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. + */ +[LinkName("SDL_GetRenderSafeArea")] public static extern bool GetRenderSafeArea(Renderer* renderer, out 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 + */ +[LinkName("SDL_SetRenderClipRect")] public static extern bool SetRenderClipRect(Renderer* renderer, 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 + */ +[LinkName("SDL_GetRenderClipRect")] public static extern bool GetRenderClipRect(Renderer* renderer, 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 + */ +[LinkName("SDL_RenderClipEnabled")] public static extern bool RenderClipEnabled(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 + */ +[LinkName("SDL_SetRenderScale")] public static extern bool SetRenderScale(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 + */ +[LinkName("SDL_GetRenderScale")] public static extern bool GetRenderScale(Renderer* renderer, out float scaleX, out 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 + */ +[LinkName("SDL_SetRenderDrawColor")] public static extern bool SetRenderDrawColor(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 + */ +[LinkName("SDL_SetRenderDrawColorFloat")] public static extern bool SetRenderDrawColorFloat(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 + */ +[LinkName("SDL_GetRenderDrawColor")] public static extern bool GetRenderDrawColor(Renderer* renderer, out Uint8 r, out Uint8 g, out Uint8 b, out 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 + */ +[LinkName("SDL_GetRenderDrawColorFloat")] public static extern bool GetRenderDrawColorFloat(Renderer* renderer, out float r, out float g, out float b, out 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 + */ +[LinkName("SDL_SetRenderColorScale")] public static extern bool SetRenderColorScale(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 + */ +[LinkName("SDL_GetRenderColorScale")] public static extern bool GetRenderColorScale(Renderer* renderer, out 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 + */ +[LinkName("SDL_SetRenderDrawBlendMode")] public static extern bool SetRenderDrawBlendMode(Renderer* renderer, 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 + */ +[LinkName("SDL_GetRenderDrawBlendMode")] public static extern bool GetRenderDrawBlendMode(Renderer* renderer, out 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 + */ +[LinkName("SDL_RenderClear")] public static extern bool RenderClear(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 + */ +[LinkName("SDL_RenderPoint")] public static extern bool RenderPoint(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 + */ +[LinkName("SDL_RenderPoints")] public static extern bool RenderPoints(Renderer* renderer, FPoint* points, c_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 + */ +[LinkName("SDL_RenderLine")] public static extern bool RenderLine(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 + */ +[LinkName("SDL_RenderLines")] public static extern bool RenderLines(Renderer* renderer, FPoint* points, c_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 + */ +[LinkName("SDL_RenderRect")] public static extern bool RenderRect(Renderer* renderer, 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 + */ +[LinkName("SDL_RenderRects")] public static extern bool RenderRects(Renderer* renderer, FRect* rects, c_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 + */ +[LinkName("SDL_RenderFillRect")] public static extern bool RenderFillRect(Renderer* renderer, 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 + */ +[LinkName("SDL_RenderFillRects")] public static extern bool RenderFillRects(Renderer* renderer, FRect* rects, c_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 + */ +[LinkName("SDL_RenderTexture")] public static extern bool RenderTexture(Renderer* renderer, Texture* texture, FRect* srcrect, 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 + */ +[LinkName("SDL_RenderTextureRotated")] public static extern bool RenderTextureRotated(Renderer* renderer, Texture* texture, FRect* srcrect, FRect* dstrect, double angle, FPoint* center, 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 + */ +[LinkName("SDL_RenderTextureAffine")] public static extern bool RenderTextureAffine(Renderer* renderer, Texture* texture, FRect* srcrect, FPoint* origin, FPoint* right, 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 + */ +[LinkName("SDL_RenderTextureTiled")] public static extern bool RenderTextureTiled(Renderer* renderer, Texture* texture, FRect* srcrect, float scale, 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 + */ +[LinkName("SDL_RenderTexture9Grid")] public static extern bool RenderTexture9Grid(Renderer* renderer, Texture* texture, FRect* srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, 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 + */ +[LinkName("SDL_RenderTexture9GridTiled")] public static extern bool RenderTexture9GridTiled(Renderer* renderer, Texture* texture, FRect* srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, 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 + */ +[LinkName("SDL_RenderGeometry")] public static extern bool RenderGeometry(Renderer* renderer, Texture* texture, Vertex* vertices, c_int num_vertices, c_int* indices, c_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 + */ +[LinkName("SDL_RenderGeometryRaw")] public static extern bool RenderGeometryRaw(Renderer* renderer, Texture* texture, float* xy, c_int xy_stride, FColor* color, c_int color_stride, float* uv, c_int uv_stride, c_int num_vertices, void* indices, c_int num_indices, c_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. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_RenderGeometry + * \sa SDL_RenderGeometryRaw + * \sa SDL_GetRenderTextureAddressMode + */ +[LinkName("SDL_SetRenderTextureAddressMode")] public static extern bool SetRenderTextureAddressMode(Renderer* renderer, TextureAddressMode u_mode, 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. + * + * \since This function is available since SDL 3.4.0. + * + * \sa SDL_SetRenderTextureAddressMode + */ +[LinkName("SDL_GetRenderTextureAddressMode")] public static extern bool GetRenderTextureAddressMode(Renderer* renderer, out TextureAddressMode u_mode, out 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. + */ +[LinkName("SDL_RenderReadPixels")] public static extern Surface* RenderReadPixels(Renderer* renderer, 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 + */ +[LinkName("SDL_RenderPresent")] public static extern bool RenderPresent(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 + */ +[LinkName("SDL_DestroyTexture")] public static extern void DestroyTexture(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 + */ +[LinkName("SDL_DestroyRenderer")] public static extern void DestroyRenderer(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. + */ +[LinkName("SDL_FlushRenderer")] public static extern bool FlushRenderer(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 + */ +[LinkName("SDL_GetRenderMetalLayer")] public static extern void* GetRenderMetalLayer(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 + */ +[LinkName("SDL_GetRenderMetalCommandEncoder")] public static extern void* GetRenderMetalCommandEncoder(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. + */ +[LinkName("SDL_AddVulkanRenderSemaphores")] public static extern bool AddVulkanRenderSemaphores(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 + */ +[LinkName("SDL_SetRenderVSync")] public static extern bool SetRenderVSync(Renderer* renderer, c_int vsync); + +public const let RENDERER_VSYNC_DISABLED = 0; +public const let 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 + */ +[LinkName("SDL_GetRenderVSync")] public static extern bool GetRenderVSync(Renderer* renderer, c_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 + */ +public const let 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 + */ +[LinkName("SDL_RenderDebugText")] public static extern bool RenderDebugText(Renderer* renderer, float x, float y, c_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 + */ +[LinkName("SDL_RenderDebugTextFormat")] public static extern bool RenderDebugTextFormat(Renderer* renderer, float x, float y, c_char* fmt, ...); + +/** + * 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 + */ +[LinkName("SDL_SetDefaultTextureScaleMode")] public static extern bool SetDefaultTextureScaleMode(Renderer* renderer, 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 + */ +[LinkName("SDL_GetDefaultTextureScaleMode")] public static extern bool GetDefaultTextureScaleMode(Renderer* renderer, 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 + */ +[CRepr] public struct GPURenderStateCreateInfo +{ + public GPUShader* fragment_shader; /**< The fragment shader to use when this render state is active */ + + public Sint32 num_sampler_bindings; /**< The number of additional fragment samplers to bind when this render state is active */ + public GPUTextureSamplerBinding* sampler_bindings; /**< Additional fragment samplers to bind when this render state is active */ + + public Sint32 num_storage_textures; /**< The number of storage textures to bind when this render state is active */ + public GPUTexture** storage_textures; /**< Storage textures to bind when this render state is active */ + + public Sint32 num_storage_buffers; /**< The number of storage buffers to bind when this render state is active */ + public GPUBuffer** storage_buffers; /**< Storage buffers to bind when this render state is active */ + + public PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} + +/** + * 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 + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_CreateGPURenderState")] public static extern GPURenderState* CreateGPURenderState(Renderer* renderer, 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. + */ +[LinkName("SDL_SetGPURenderStateFragmentUniforms")] public static extern bool SetGPURenderStateFragmentUniforms(GPURenderState* state, Uint32 slot_index, 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. + */ +[LinkName("SDL_SetGPURenderState")] public static extern bool SetGPURenderState(Renderer* renderer, 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 + */ +[LinkName("SDL_DestroyGPURenderState")] public static extern void DestroyGPURenderState(GPURenderState* state); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_render_h_ */ \ No newline at end of file diff --git a/src/SDL_revision.bf b/src/SDL_revision.bf new file mode 100644 index 0000000..a4bd032 --- /dev/null +++ b/src/SDL_revision.bf @@ -0,0 +1,8 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + diff --git a/src/SDL_scancode.bf b/src/SDL_scancode.bf new file mode 100644 index 0000000..03e8b0c --- /dev/null +++ b/src/SDL_scancode.bf @@ -0,0 +1,442 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # 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 + */ + + + + + + +/** + * 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 `scancode` field of the SDL_KeyboardEvent structure. + * + * The values in this enumeration are based on the USB usage page standard: + * https://usb.org/sites/default/files/hut1_5.pdf + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum Scancode : c_int +{ + Unknown = 0, + + /** + * \name Usage page 0x07 + * + * These values are from usage page 0x07 (USB keyboard page). + */ + /* @{ */ + + A = 4, + B = 5, + C = 6, + D = 7, + E = 8, + F = 9, + G = 10, + H = 11, + I = 12, + J = 13, + K = 14, + L = 15, + M = 16, + N = 17, + O = 18, + P = 19, + Q = 20, + R = 21, + S = 22, + T = 23, + U = 24, + V = 25, + W = 26, + X = 27, + Y = 28, + Z = 29, + + _1 = 30, + _2 = 31, + _3 = 32, + _4 = 33, + _5 = 34, + _6 = 35, + _7 = 36, + _8 = 37, + _9 = 38, + _0 = 39, + + Return = 40, + Escape = 41, + Backspace = 42, + Tab = 43, + Space = 44, + + Minus = 45, + Equals = 46, + Leftbracket = 47, + Rightbracket = 48, + Backslash = 49, /**< Located at the lower left of the return + * key on ISO keyboards and at the right end + * of the QWERTY row on ANSI keyboards. + * Produces REVERSE SOLIDUS (backslash) and + * VERTICAL LINE in a US layout, REVERSE + * SOLIDUS and VERTICAL LINE in a UK Mac + * layout, NUMBER SIGN and TILDE in a UK + * Windows layout, DOLLAR SIGN and POUND SIGN + * in a Swiss German layout, NUMBER SIGN and + * APOSTROPHE in a German layout, GRAVE + * ACCENT and POUND SIGN in a French Mac + * layout, and ASTERISK and MICRO SIGN in a + * French Windows layout. + */ + Nonushash = 50, /**< ISO USB keyboards actually use this code + * instead of 49 for the same key, but all + * OSes I've seen treat the two codes + * identically. So, as an implementor, unless + * your keyboard generates both of those + * codes and your OS treats them differently, + * you should generate SDL_SCANCODE_BACKSLASH + * instead of this code. As a user, you + * should not rely on this code because SDL + * will never generate it with most (all?) + * keyboards. + */ + Semicolon = 51, + Apostrophe = 52, + Grave = 53, /**< Located in the top left corner (on both ANSI + * and ISO keyboards). Produces GRAVE ACCENT and + * TILDE in a US Windows layout and in US and UK + * Mac layouts on ANSI keyboards, GRAVE ACCENT + * and NOT SIGN in a UK Windows layout, SECTION + * SIGN and PLUS-MINUS SIGN in US and UK Mac + * layouts on ISO keyboards, SECTION SIGN and + * DEGREE SIGN in a Swiss German layout (Mac: + * only on ISO keyboards), CIRCUMFLEX ACCENT and + * DEGREE SIGN in a German layout (Mac: only on + * ISO keyboards), SUPERSCRIPT TWO and TILDE in a + * French Windows layout, COMMERCIAL AT and + * NUMBER SIGN in a French Mac layout on ISO + * keyboards, and LESS-THAN SIGN and GREATER-THAN + * SIGN in a Swiss German, German, or French Mac + * layout on ANSI keyboards. + */ + Comma = 54, + Period = 55, + Slash = 56, + + Capslock = 57, + + F1 = 58, + F2 = 59, + F3 = 60, + F4 = 61, + F5 = 62, + F6 = 63, + F7 = 64, + F8 = 65, + F9 = 66, + F10 = 67, + F11 = 68, + F12 = 69, + + Printscreen = 70, + Scrolllock = 71, + Pause = 72, + Insert = 73, /**< insert on PC, help on some Mac keyboards (but + does send code 73, not 117) */ + Home = 74, + Pageup = 75, + Delete = 76, + End = 77, + Pagedown = 78, + Right = 79, + Left = 80, + Down = 81, + Up = 82, + + Numlockclear = 83, /**< num lock on PC, clear on Mac keyboards + */ + KpDivide = 84, + KpMultiply = 85, + KpMinus = 86, + KpPlus = 87, + KpEnter = 88, + Kp1 = 89, + Kp2 = 90, + Kp3 = 91, + Kp4 = 92, + Kp5 = 93, + Kp6 = 94, + Kp7 = 95, + Kp8 = 96, + Kp9 = 97, + Kp0 = 98, + KpPeriod = 99, + + Nonusbackslash = 100, /**< This is the additional key that ISO + * keyboards have over ANSI ones, + * 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 + * US or UK Windows layout, and + * LESS-THAN SIGN and GREATER-THAN SIGN + * in a Swiss German, German, or French + * layout. */ + Application = 101, /**< windows contextual menu, compose */ + Power = 102, /**< The USB document says this is a status flag, + * not a physical key - but some Mac keyboards + * do have a power key. */ + KpEquals = 103, + F13 = 104, + F14 = 105, + F15 = 106, + F16 = 107, + F17 = 108, + F18 = 109, + F19 = 110, + F20 = 111, + F21 = 112, + F22 = 113, + F23 = 114, + F24 = 115, + Execute = 116, + Help = 117, /**< AL Integrated Help Center */ + Menu = 118, /**< Menu (show menu) */ + Select = 119, + Stop = 120, /**< AC Stop */ + Again = 121, /**< AC Redo/Repeat */ + Undo = 122, /**< AC Undo */ + Cut = 123, /**< AC Cut */ + Copy = 124, /**< AC Copy */ + Paste = 125, /**< AC Paste */ + Find = 126, /**< AC Find */ + Mute = 127, + Volumeup = 128, + Volumedown = 129, +/* not sure whether there's a reason to enable these */ +/* SDL_SCANCODE_LOCKINGCAPSLOCK = 130, */ +/* SDL_SCANCODE_LOCKINGNUMLOCK = 131, */ +/* SDL_SCANCODE_LOCKINGSCROLLLOCK = 132, */ + KpComma = 133, + KpEqualsas400 = 134, + + International1 = 135, /**< used on Asian keyboards, see + footnotes in USB doc */ + International2 = 136, + International3 = 137, /**< Yen */ + International4 = 138, + International5 = 139, + International6 = 140, + International7 = 141, + International8 = 142, + International9 = 143, + Lang1 = 144, /**< Hangul/English toggle */ + Lang2 = 145, /**< Hanja conversion */ + Lang3 = 146, /**< Katakana */ + Lang4 = 147, /**< Hiragana */ + Lang5 = 148, /**< Zenkaku/Hankaku */ + Lang6 = 149, /**< reserved */ + Lang7 = 150, /**< reserved */ + Lang8 = 151, /**< reserved */ + Lang9 = 152, /**< reserved */ + + Alterase = 153, /**< Erase-Eaze */ + Sysreq = 154, + Cancel = 155, /**< AC Cancel */ + Clear = 156, + Prior = 157, + Return2 = 158, + Separator = 159, + Out = 160, + Oper = 161, + Clearagain = 162, + Crsel = 163, + Exsel = 164, + + Kp00 = 176, + Kp000 = 177, + Thousandsseparator = 178, + Decimalseparator = 179, + Currencyunit = 180, + Currencysubunit = 181, + KpLeftparen = 182, + KpRightparen = 183, + KpLeftbrace = 184, + KpRightbrace = 185, + KpTab = 186, + KpBackspace = 187, + KpA = 188, + KpB = 189, + KpC = 190, + KpD = 191, + KpE = 192, + KpF = 193, + KpXor = 194, + KpPower = 195, + KpPercent = 196, + KpLess = 197, + KpGreater = 198, + KpAmpersand = 199, + KpDblampersand = 200, + KpVerticalbar = 201, + KpDblverticalbar = 202, + KpColon = 203, + KpHash = 204, + KpSpace = 205, + KpAt = 206, + KpExclam = 207, + KpMemstore = 208, + KpMemrecall = 209, + KpMemclear = 210, + KpMemadd = 211, + KpMemsubtract = 212, + KpMemmultiply = 213, + KpMemdivide = 214, + KpPlusminus = 215, + KpClear = 216, + KpClearentry = 217, + KpBinary = 218, + KpOctal = 219, + KpDecimal = 220, + KpHexadecimal = 221, + + Lctrl = 224, + Lshift = 225, + Lalt = 226, /**< alt, option */ + Lgui = 227, /**< windows, command (apple), meta */ + Rctrl = 228, + Rshift = 229, + Ralt = 230, /**< alt gr, option */ + Rgui = 231, /**< windows, command (apple), meta */ + + Mode = 257, /**< I'm not sure if this is really not covered + * by any of the above, but since there's a + * special SDL_KMOD_MODE for it I'm adding it here + */ + + /* @} */ /* Usage page 0x07 */ + + /** + * \name Usage page 0x0C + * + * These values are mapped from usage page 0x0C (USB consumer page). + * + * 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 + * real world usage. + */ + /* @{ */ + + Sleep = 258, /**< Sleep */ + Wake = 259, /**< Wake */ + + ChannelIncrement = 260, /**< Channel Increment */ + ChannelDecrement = 261, /**< Channel Decrement */ + + MediaPlay = 262, /**< Play */ + MediaPause = 263, /**< Pause */ + MediaRecord = 264, /**< Record */ + MediaFastForward = 265, /**< Fast Forward */ + MediaRewind = 266, /**< Rewind */ + MediaNextTrack = 267, /**< Next Track */ + MediaPreviousTrack = 268, /**< Previous Track */ + MediaStop = 269, /**< Stop */ + MediaEject = 270, /**< Eject */ + MediaPlayPause = 271, /**< Play / Pause */ + MediaSelect = 272, /* Media Select */ + + AcNew = 273, /**< AC New */ + AcOpen = 274, /**< AC Open */ + AcClose = 275, /**< AC Close */ + AcExit = 276, /**< AC Exit */ + AcSave = 277, /**< AC Save */ + AcPrint = 278, /**< AC Print */ + AcProperties = 279, /**< AC Properties */ + + AcSearch = 280, /**< AC Search */ + AcHome = 281, /**< AC Home */ + AcBack = 282, /**< AC Back */ + AcForward = 283, /**< AC Forward */ + AcStop = 284, /**< AC Stop */ + AcRefresh = 285, /**< AC Refresh */ + AcBookmarks = 286, /**< AC Bookmarks */ + + /* @} */ /* Usage page 0x0C */ + + + /** + * \name Mobile keys + * + * These are values that are often used on mobile phones. + */ + /* @{ */ + + Softleft = 287, /**< Usually situated below the display on phones and + used as a multi-function feature key for selecting + a software defined function shown on the bottom left + of the display. */ + Softright = 288, /**< Usually situated below the display on phones and + used as a multi-function feature key for selecting + a software defined function shown on the bottom right + of the display. */ + Call = 289, /**< Used for accepting phone calls. */ + Endcall = 290, /**< Used for rejecting phone calls. */ + + /* @} */ /* Mobile keys */ + + /* Add any other keys here. */ + + Reserved = 400, /**< 400-500 reserved for dynamic keycodes */ + + Count = 512, +} + +/**< not a key, just marks the number of scancodes for array bounds */ + +} + +/* SDL_scancode_h_ */ \ No newline at end of file diff --git a/src/SDL_sensor.bf b/src/SDL_sensor.bf new file mode 100644 index 0000000..4bbf4ce --- /dev/null +++ b/src/SDL_sensor.bf @@ -0,0 +1,331 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + +/** + * # CategorySensor + * + * 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + +/* *INDENT-OFF* */ + +/* *INDENT-ON* */ + + +/** + * The opaque structure used to identify an opened SDL sensor. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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 value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias SensorID = Uint32; + +/** + * 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. + */ +public const let STANDARD_GRAVITY = 9.80665f; + +/** + * The different sensors defined by SDL. + * + * Additional sensors may be available, using platform dependent semantics. + * + * Here are the additional Android sensors: + * + * https://developer.android.com/reference/android/hardware/SensorEvent.html#values + * + * Accelerometer sensor notes: + * + * 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. + * + * - `values[0]`: Acceleration on the x axis + * - `values[1]`: Acceleration on the y axis + * - `values[2]`: Acceleration on the z axis + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The accelerometer axis data is not changed when the device is rotated. + * + * Gyroscope sensor notes: + * + * The gyroscope returns the current rate of rotation in radians per second. + * The rotation is positive in the counter-clockwise direction. That is, an + * observer looking from a positive location on one of the axes would see + * positive rotation on that axis when it appeared to be rotating + * counter-clockwise. + * + * - `values[0]`: Angular speed around the x axis (pitch) + * - `values[1]`: Angular speed around the y axis (yaw) + * - `values[2]`: Angular speed around the z axis (roll) + * + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer + * + * The gyroscope axis data is not changed when the device is rotated. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentDisplayOrientation + */ +[AllowDuplicates] public enum SensorType : c_int +{ + Invalid = -1, /**< Returned for an invalid sensor */ + Unknown, /**< Unknown sensor type */ + Accel, /**< Accelerometer */ + Gyro, /**< Gyroscope */ + AccelL, /**< Accelerometer for left Joy-Con controller and Wii nunchuk */ + GyroL, /**< Gyroscope for left Joy-Con controller */ + AccelR, /**< Accelerometer for right Joy-Con controller */ + GyroR, /**< Gyroscope for right Joy-Con controller */ + Count, +} + + +/* Function prototypes */ + +/** + * Get a list of currently connected 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. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetSensors")] public static extern SensorID* GetSensors(out c_int count); + +/** + * Get the implementation dependent name of a sensor. + * + * This can be called before any sensors are opened. + * + * \param instance_id the sensor instance ID. + * \returns the sensor name, or NULL if `instance_id` is not valid. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetSensorNameForID")] public static extern c_char* GetSensorNameForID(SensorID instance_id); + +/** + * Get the type of a sensor. + * + * This can be called before any sensors are opened. + * + * \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. + */ +[LinkName("SDL_GetSensorTypeForID")] public static extern SensorType GetSensorTypeForID(SensorID instance_id); + +/** + * Get the platform dependent type of a sensor. + * + * This can be called before any sensors are opened. + * + * \param instance_id the sensor instance ID. + * \returns the sensor platform dependent type, or -1 if `instance_id` is not + * valid. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetSensorNonPortableTypeForID")] public static extern c_int GetSensorNonPortableTypeForID(SensorID instance_id); + +/** + * Open a sensor for use. + * + * \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 3.2.0. + */ +[LinkName("SDL_OpenSensor")] public static extern Sensor* OpenSensor(SensorID instance_id); + +/** + * Return the SDL_Sensor associated with an instance ID. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetSensorFromID")] public static extern Sensor* GetSensorFromID(SensorID instance_id); + +/** + * Get the properties associated with a sensor. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetSensorProperties")] public static extern PropertiesID GetSensorProperties(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. + */ +[LinkName("SDL_GetSensorName")] public static extern c_char* GetSensorName(Sensor* sensor); + +/** + * Get the type of a sensor. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetSensorType")] public static extern SensorType GetSensorType(Sensor* sensor); + +/** + * Get the platform dependent type of a sensor. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetSensorNonPortableType")] public static extern c_int GetSensorNonPortableType(Sensor* sensor); + +/** + * Get the instance ID of a sensor. + * + * \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 3.2.0. + */ +[LinkName("SDL_GetSensorID")] public static extern SensorID GetSensorID(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 true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetSensorData")] public static extern bool GetSensorData(Sensor* sensor, float* data, c_int num_values); + +/** + * Close a sensor previously opened with SDL_OpenSensor(). + * + * \param sensor the SDL_Sensor object to close. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_CloseSensor")] public static extern void CloseSensor(Sensor* sensor); + +/** + * Update the current state of the open sensors. + * + * This is called automatically by the event loop if sensor events are + * enabled. + * + * This needs to be called from the thread that initialized the sensor + * subsystem. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_UpdateSensors")] public static extern void UpdateSensors(); +} + +/* Ends C function definitions when using C++ */ + +/* *INDENT-OFF* */ + +/* *INDENT-ON* */ + + + +/* SDL_sensor_h_ */ \ No newline at end of file diff --git a/src/SDL_stdinc.bf b/src/SDL_stdinc.bf new file mode 100644 index 0000000..72e7fc3 --- /dev/null +++ b/src/SDL_stdinc.bf @@ -0,0 +1,6163 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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(). + */ + + + + + + + + + + +/* Most everything except Visual Studio 2008 and earlier has stdint.h now */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + /* Visual Studio 2017 */ + + + + + + + + +/* !__cplusplus */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/** + * 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. + */ + + +/* long long introduced in Visual Studio.NET 2003 */ + + + + + + +/** + * 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. + */ + + + + + + + + + + + +/** + * 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 + */ + + +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ + + + + + + + + +/* !SDL_COMPILE_TIME_ASSERT */ + + +/* universal, but may trigger -Wunused-local-typedefs */ + + + + +/** + * 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. + */ + + +/** + * Macro useful for building other macros with strings in them. + * + * For example: + * + * ```c + * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` + * ``` + * + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. + */ + + +/** + * \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). + */ +/* @{ */ + + + +/** + * 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 + */ +/* 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 + */ +/* 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 + */ +/* or `((type)(expression))` in C */ + + + + + + + + + + + +/* @} */ /* 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. + */ + + + + + + + + +/** + * 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 + */ +/* 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 + */ +/* or whatever the current compiler uses. */ + +/* !SDL_WIKI_DOCUMENTATION_SECTION */ + + + + + + + + + + + +/* !SDL_SINT64_C */ + + + + + + + + + + + +/* !SDL_UINT64_C */ + +/* !SDL_WIKI_DOCUMENTATION_SECTION */ + +/** + * \name Basic data types + */ +/* @{ */ + +/** + * A signed 8-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Sint8 = int8; +public const let MAX_SINT8 = ((Sint8)0x7F);/* 127 */ +public const let MIN_SINT8 = ((Sint8)(~0x7F));/* -128 */ + +/** + * An unsigned 8-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Uint8 = uint8; +public const let MAX_UINT8 = ((Uint8)0xFF);/* 255 */ +public const let MIN_UINT8 = ((Uint8)0x00);/* 0 */ + +/** + * A signed 16-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Sint16 = int16; +public const let MAX_SINT16 = ((Sint16)0x7FFF);/* 32767 */ +public const let MIN_SINT16 = ((Sint16)(~0x7FFF));/* -32768 */ + +/** + * An unsigned 16-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Uint16 = uint16; +public const let MAX_UINT16 = ((Uint16)0xFFFF);/* 65535 */ +public const let MIN_UINT16 = ((Uint16)0x0000);/* 0 */ + +/** + * A signed 32-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Sint32 = int32; +public const let MAX_SINT32 = ((Sint32)0x7FFFFFFF);/* 2147483647 */ +public const let MIN_SINT32 = ((Sint32)(~0x7FFFFFFF));/* -2147483648 */ + +/** + * An unsigned 32-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + */ +public typealias Uint32 = uint32; +public const let MAX_UINT32 = ((Uint32)0xFFFFFFFFu);/* 4294967295 */ +public const let 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 + */ +public typealias Sint64 = int64; +public const let MAX_SINT64 = SINT64_C(0x7FFFFFFFFFFFFFFF);/* 9223372036854775807 */ +public const let MIN_SINT64 = ~SINT64_C(0x7FFFFFFFFFFFFFFF);/* -9223372036854775808 */ + +/** + * An unsigned 64-bit integer type. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_UINT64_C + */ +public typealias Uint64 = uint64; +public const let MAX_UINT64 = UINT64_C(0xFFFFFFFFFFFFFFFF);/* 18446744073709551615 */ +public const let MIN_UINT64 = 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 + */ +public typealias Time = Sint64; +public const let MAX_TIME = MAX_SINT64; +public const let MIN_TIME = MIN_SINT64; + +/* @} */ /* Basic data types */ + +/** + * \name Floating-point constants + */ +/* @{ */ + + + + + +/** + * 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. + */ +public const let FLT_EPSILON = 1.1920928955078125e-07F;/* 0x0.000002p0 */ + + +/* @} */ /* Floating-point constants */ + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + +/* 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) */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/* Specifically for the `long long` -- SDL-specific. */ + + +/* using I64 for windows - make sure `long long` is 64 bits. */ + + + + + + + + + + + + + + + + + + +/* Annotations to help code analysis tools */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ +/* __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. + */ +/* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + + + + + + + + + + + + + + + + + +/* VS 2010 and above */ + + + + + + + + + + + + + + + + + + + + + + + + + + +/* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ +/* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + + + + + + + + +/* SDL_DISABLE_ANALYZE_MACROS */ + +/** \cond */ + + + + + + + + + + + + + + +[CRepr] public struct alignment_test +{ + public Uint8 a; + public void* b; +} + + +/* 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 */ + + +/* TODO: include/SDL_stdinc.h:390: error: size of array 'SDL_dummy_enum' is negative */ +[AllowDuplicates] public enum DUMMY_ENUM : c_int +{ + DUMMY_ENUM_VALUE, +} + + + +/* DOXYGEN_SHOULD_IGNORE_THIS */ +/** \endcond */ + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ + + + + + + + + + +/** + * 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 + */ + + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ + + + + + + + + + +/** + * 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 + */ +[LinkName("SDL_malloc")] public static extern void* malloc(c_size 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 + */ +[LinkName("SDL_calloc")] public static extern void* calloc(c_size nmemb, c_size 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 + */ +[LinkName("SDL_realloc")] public static extern void* realloc(void* mem, c_size 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 + */ +[LinkName("SDL_free")] public static extern void 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 + */ +public function void* malloc_func(c_size 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 + */ +public function void* calloc_func(c_size nmemb, c_size 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 + */ +public function void* realloc_func(void* mem, c_size 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 + */ +public function void 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. + */ +[LinkName("SDL_GetOriginalMemoryFunctions")] public static extern void GetOriginalMemoryFunctions(malloc_func* malloc_func, calloc_func* calloc_func, realloc_func* realloc_func, 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 + */ +[LinkName("SDL_GetMemoryFunctions")] public static extern void GetMemoryFunctions(malloc_func* malloc_func, calloc_func* calloc_func, realloc_func* realloc_func, 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 + */ +[LinkName("SDL_SetMemoryFunctions")] public static extern bool SetMemoryFunctions(malloc_func malloc_func, calloc_func calloc_func, realloc_func realloc_func, 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 + */ +[LinkName("SDL_aligned_alloc")] public static extern void* aligned_alloc(c_size alignment, c_size 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 + */ +[LinkName("SDL_aligned_free")] public static extern void 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. + */ +[LinkName("SDL_GetNumAllocations")] public static extern c_int GetNumAllocations(); + +/** + * 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 + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_GetEnvironment")] public static extern Environment* GetEnvironment(); + +/** + * 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 + */ +[LinkName("SDL_CreateEnvironment")] public static extern Environment* 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 + */ +[LinkName("SDL_GetEnvironmentVariable")] public static extern c_char* GetEnvironmentVariable(Environment* env, c_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 + */ +[LinkName("SDL_GetEnvironmentVariables")] public static extern c_char** GetEnvironmentVariables(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 + */ +[LinkName("SDL_SetEnvironmentVariable")] public static extern bool SetEnvironmentVariable(Environment* env, c_char* name, c_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 + */ +[LinkName("SDL_UnsetEnvironmentVariable")] public static extern bool UnsetEnvironmentVariable(Environment* env, c_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 + */ +[LinkName("SDL_DestroyEnvironment")] public static extern void DestroyEnvironment(Environment* env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_getenv")] public static extern c_char* getenv(c_char* name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +[LinkName("SDL_getenv_unsafe")] public static extern c_char* getenv_unsafe(c_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 + */ +[LinkName("SDL_setenv_unsafe")] public static extern c_int setenv_unsafe(c_char* name, c_char* value, c_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 + */ +[LinkName("SDL_unsetenv_unsafe")] public static extern c_int unsetenv_unsafe(c_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 + */ +public function c_int CompareCallback(void* a, 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 + */ +[LinkName("SDL_qsort")] public static extern void qsort(void* @base, c_size nmemb, c_size size, 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 + */ +[LinkName("SDL_bsearch")] public static extern void* bsearch(void* key, void* @base, c_size nmemb, c_size size, 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 + */ +public function c_int CompareCallback_r(void* userdata, void* a, 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 + */ +[LinkName("SDL_qsort_r")] public static extern void qsort_r(void* @base, c_size nmemb, c_size size, 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 + */ +[LinkName("SDL_bsearch_r")] public static extern void* bsearch_r(void* key, void* @base, c_size nmemb, c_size size, 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. + */ +[LinkName("SDL_abs")] public static extern c_int abs(c_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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ +[LinkName("SDL_isalpha")] public static extern c_int isalpha(c_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. + */ +[LinkName("SDL_isalnum")] public static extern c_int isalnum(c_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. + */ +[LinkName("SDL_isblank")] public static extern c_int isblank(c_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. + */ +[LinkName("SDL_iscntrl")] public static extern c_int iscntrl(c_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. + */ +[LinkName("SDL_isdigit")] public static extern c_int isdigit(c_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. + */ +[LinkName("SDL_isxdigit")] public static extern c_int isxdigit(c_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 + */ +[LinkName("SDL_ispunct")] public static extern c_int ispunct(c_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. + */ +[LinkName("SDL_isspace")] public static extern c_int isspace(c_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. + */ +[LinkName("SDL_isupper")] public static extern c_int isupper(c_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. + */ +[LinkName("SDL_islower")] public static extern c_int islower(c_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. + */ +[LinkName("SDL_isprint")] public static extern c_int isprint(c_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 + */ +[LinkName("SDL_isgraph")] public static extern c_int isgraph(c_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. + */ +[LinkName("SDL_toupper")] public static extern c_int toupper(c_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. + */ +[LinkName("SDL_tolower")] public static extern c_int tolower(c_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. + */ +[LinkName("SDL_crc16")] public static extern Uint16 crc16(Uint16 crc, void* data, c_size 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. + */ +[LinkName("SDL_crc32")] public static extern Uint32 crc32(Uint32 crc, void* data, c_size 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. + */ +[LinkName("SDL_murmur3_32")] public static extern Uint32 murmur3_32(void* data, c_size 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 + */ +[LinkName("SDL_memcpy")] public static extern void* memcpy(void* dst, void* src, c_size len); + +/* Take advantage of compiler optimizations for memcpy */ + + + + + + + + +/** + * 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. + */ + + + + +/** + * 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 + */ +[LinkName("SDL_memmove")] public static extern void* memmove(void* dst, void* src, c_size len); + +/* Take advantage of compiler optimizations for memmove */ + + + + + + + +/** + * 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. + */ +[LinkName("SDL_memset")] public static extern void* memset(void* dst, c_int c, c_size 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. + */ +[LinkName("SDL_memset4")] public static extern void* memset4(void* dst, Uint32 val, c_size dwords); + +/* Take advantage of compiler optimizations for memset */ + + + + + + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + + +/** + * 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. + */ +[LinkName("SDL_memcmp")] public static extern c_int memcmp(void* s1, void* s2, c_size 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 + */ +[LinkName("SDL_wcslen")] public static extern c_size wcslen(c_wchar* 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 + */ +[LinkName("SDL_wcsnlen")] public static extern c_size wcsnlen(c_wchar* wstr, c_size 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 + */ +[LinkName("SDL_wcslcpy")] public static extern c_size wcslcpy(c_wchar* dst, c_wchar* src, c_size 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 + */ +[LinkName("SDL_wcslcat")] public static extern c_size wcslcat(c_wchar* dst, c_wchar* src, c_size 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. + */ +[LinkName("SDL_wcsdup")] public static extern c_wchar* wcsdup(c_wchar* 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. + */ +[LinkName("SDL_wcsstr")] public static extern c_wchar* wcsstr(c_wchar* haystack, c_wchar* 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. + */ +[LinkName("SDL_wcsnstr")] public static extern c_wchar* wcsnstr(c_wchar* haystack, c_wchar* needle, c_size 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. + */ +[LinkName("SDL_wcscmp")] public static extern c_int wcscmp(c_wchar* str1, c_wchar* 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. + */ +[LinkName("SDL_wcsncmp")] public static extern c_int wcsncmp(c_wchar* str1, c_wchar* str2, c_size 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. + */ +[LinkName("SDL_wcscasecmp")] public static extern c_int wcscasecmp(c_wchar* str1, c_wchar* 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. + */ +[LinkName("SDL_wcsncasecmp")] public static extern c_int wcsncasecmp(c_wchar* str1, c_wchar* str2, c_size 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 + */ +[LinkName("SDL_wcstol")] public static extern c_long wcstol(c_wchar* str, c_wchar** endp, c_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 + */ +[LinkName("SDL_strlen")] public static extern c_size strlen(c_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 + */ +[LinkName("SDL_strnlen")] public static extern c_size strnlen(c_char* str, c_size 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 + */ +[LinkName("SDL_strlcpy")] public static extern c_size strlcpy(c_char* dst, c_char* src, c_size 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 + */ +[LinkName("SDL_utf8strlcpy")] public static extern c_size utf8strlcpy(c_char* dst, c_char* src, c_size 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 + */ +[LinkName("SDL_strlcat")] public static extern c_size strlcat(c_char* dst, c_char* src, c_size 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. + */ +[LinkName("SDL_strdup")] public static extern c_char* strdup(c_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. + */ +[LinkName("SDL_strndup")] public static extern c_char* strndup(c_char* str, c_size 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. + */ +[LinkName("SDL_strrev")] public static extern c_char* strrev(c_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 + */ +[LinkName("SDL_strupr")] public static extern c_char* strupr(c_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 + */ +[LinkName("SDL_strlwr")] public static extern c_char* strlwr(c_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. + */ +[LinkName("SDL_strchr")] public static extern c_char* strchr(c_char* str, c_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. + */ +[LinkName("SDL_strrchr")] public static extern c_char* strrchr(c_char* str, c_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. + */ +[LinkName("SDL_strstr")] public static extern c_char* strstr(c_char* haystack, c_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. + */ +[LinkName("SDL_strnstr")] public static extern c_char* strnstr(c_char* haystack, c_char* needle, c_size 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. + */ +[LinkName("SDL_strcasestr")] public static extern c_char* strcasestr(c_char* haystack, c_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. + */ +[LinkName("SDL_strtok_r")] public static extern c_char* strtok_r(c_char* str, c_char* delim, c_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 + */ +[LinkName("SDL_utf8strlen")] public static extern c_size utf8strlen(c_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 + */ +[LinkName("SDL_utf8strnlen")] public static extern c_size utf8strnlen(c_char* str, c_size 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 + */ +[LinkName("SDL_itoa")] public static extern c_char* itoa(c_int value, c_char* str, c_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 + */ +[LinkName("SDL_uitoa")] public static extern c_char* uitoa(c_uint value, c_char* str, c_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 + */ +[LinkName("SDL_ltoa")] public static extern c_char* ltoa(c_long value, c_char* str, c_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 + */ +[LinkName("SDL_ultoa")] public static extern c_char* ultoa(c_ulong value, c_char* str, c_int radix); + + + +/** + * 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 + */ +[LinkName("SDL_lltoa")] public static extern c_char* lltoa(c_longlong value, c_char* str, c_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 + */ +[LinkName("SDL_ulltoa")] public static extern c_char* ulltoa(c_ulonglong value, c_char* str, c_int radix); + + +/** + * 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 + */ +[LinkName("SDL_atoi")] public static extern c_int atoi(c_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 + */ +[LinkName("SDL_atof")] public static extern double atof(c_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 + */ +[LinkName("SDL_strtol")] public static extern c_long strtol(c_char* str, c_char** endp, c_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 + */ +[LinkName("SDL_strtoul")] public static extern c_ulong strtoul(c_char* str, c_char** endp, c_int @base); + + + +/** + * 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 + */ +[LinkName("SDL_strtoll")] public static extern c_longlong strtoll(c_char* str, c_char** endp, c_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 + */ +[LinkName("SDL_strtoull")] public static extern c_ulonglong strtoull(c_char* str, c_char** endp, c_int @base); + + +/** + * 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 + */ +[LinkName("SDL_strtod")] public static extern double strtod(c_char* str, c_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. + */ +[LinkName("SDL_strcmp")] public static extern c_int strcmp(c_char* str1, c_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. + */ +[LinkName("SDL_strncmp")] public static extern c_int strncmp(c_char* str1, c_char* str2, c_size 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. + */ +[LinkName("SDL_strcasecmp")] public static extern c_int strcasecmp(c_char* str1, c_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. + */ +[LinkName("SDL_strncasecmp")] public static extern c_int strncasecmp(c_char* str1, c_char* str2, c_size 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. + */ +[LinkName("SDL_strpbrk")] public static extern c_char* strpbrk(c_char* str, c_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 + */ +public const let 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. + */ +[LinkName("SDL_StepUTF8")] public static extern Uint32 StepUTF8(c_char** pstr, c_size* 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. + */ +[LinkName("SDL_StepBackUTF8")] public static extern Uint32 StepBackUTF8(c_char* start, c_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. + */ +[LinkName("SDL_UCS4ToUTF8")] public static extern c_char* UCS4ToUTF8(Uint32 codepoint, c_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. + */ +[LinkName("SDL_sscanf")] public static extern c_int sscanf(c_char* text, c_char* fmt, ...); + +/** + * 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. + */ +[LinkName("SDL_vsscanf")] public static extern c_int vsscanf(c_char* text, c_char* fmt, VarArgs ap); + +/** + * 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. + */ +[LinkName("SDL_snprintf")] public static extern c_int snprintf(c_char* text, c_size maxlen, c_char* fmt, ...); + +/** + * 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. + */ +[LinkName("SDL_swprintf")] public static extern c_int swprintf(c_wchar* text, c_size maxlen, c_wchar* fmt, ...); + +/** + * 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. + */ +[LinkName("SDL_vsnprintf")] public static extern c_int vsnprintf(c_char* text, c_size maxlen, c_char* fmt, VarArgs ap); + +/** + * 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. + */ +[LinkName("SDL_vswprintf")] public static extern c_int vswprintf(c_wchar* text, c_size maxlen, c_wchar* fmt, VarArgs ap); + +/** + * 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. + */ +[LinkName("SDL_asprintf")] public static extern c_int asprintf(c_char** strp, c_char* fmt, ...); + +/** + * 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. + */ +[LinkName("SDL_vasprintf")] public static extern c_int vasprintf(c_char** strp, c_char* fmt, VarArgs ap); + +/** + * 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 + */ +[LinkName("SDL_srand")] public static extern void 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 + */ +[LinkName("SDL_rand")] public static extern Sint32 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 + */ +[LinkName("SDL_randf")] public static extern float randf(); + +/** + * 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 + */ +[LinkName("SDL_rand_bits")] public static extern Uint32 rand_bits(); + +/** + * 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 + */ +[LinkName("SDL_rand_r")] public static extern Sint32 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 + */ +[LinkName("SDL_randf_r")] public static extern float 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 + */ +[LinkName("SDL_rand_bits_r")] public static extern Uint32 rand_bits_r(Uint64* state); + + + +/** + * 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 + */ +public const let PI_D = 3.141592653589793238462643383279502884;/**< pi (double) */ + + + + +/** + * 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 + */ +public const let PI_F = 3.141592653589793238462643383279502884F;/**< pi (float) */ + + +/** + * 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 + */ +[LinkName("SDL_acos")] public static extern double 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 + */ +[LinkName("SDL_acosf")] public static extern float 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 + */ +[LinkName("SDL_asin")] public static extern double 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 + */ +[LinkName("SDL_asinf")] public static extern float 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 + */ +[LinkName("SDL_atan")] public static extern double 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 + */ +[LinkName("SDL_atanf")] public static extern float 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 + */ +[LinkName("SDL_atan2")] public static extern double 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 + */ +[LinkName("SDL_atan2f")] public static extern float 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 + */ +[LinkName("SDL_ceil")] public static extern double 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 + */ +[LinkName("SDL_ceilf")] public static extern float 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 + */ +[LinkName("SDL_copysign")] public static extern double 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 + */ +[LinkName("SDL_copysignf")] public static extern float 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 + */ +[LinkName("SDL_cos")] public static extern double 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 + */ +[LinkName("SDL_cosf")] public static extern float 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 + */ +[LinkName("SDL_exp")] public static extern double 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 + */ +[LinkName("SDL_expf")] public static extern float 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 + */ +[LinkName("SDL_fabs")] public static extern double 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 + */ +[LinkName("SDL_fabsf")] public static extern float 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 + */ +[LinkName("SDL_floor")] public static extern double 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 + */ +[LinkName("SDL_floorf")] public static extern float 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 + */ +[LinkName("SDL_trunc")] public static extern double 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 + */ +[LinkName("SDL_truncf")] public static extern float 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 + */ +[LinkName("SDL_fmod")] public static extern double 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 + */ +[LinkName("SDL_fmodf")] public static extern float 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 + */ +[LinkName("SDL_isinf")] public static extern c_int 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 + */ +[LinkName("SDL_isinff")] public static extern c_int 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 + */ +[LinkName("SDL_isnan")] public static extern c_int 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 + */ +[LinkName("SDL_isnanf")] public static extern c_int 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 + */ +[LinkName("SDL_log")] public static extern double 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 + */ +[LinkName("SDL_logf")] public static extern float 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 + */ +[LinkName("SDL_log10")] public static extern double 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 + */ +[LinkName("SDL_log10f")] public static extern float 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 + */ +[LinkName("SDL_modf")] public static extern double 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 + */ +[LinkName("SDL_modff")] public static extern float 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 + */ +[LinkName("SDL_pow")] public static extern double 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 + */ +[LinkName("SDL_powf")] public static extern float 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 + */ +[LinkName("SDL_round")] public static extern double 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 + */ +[LinkName("SDL_roundf")] public static extern float 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 + */ +[LinkName("SDL_lround")] public static extern c_long 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 + */ +[LinkName("SDL_lroundf")] public static extern c_long 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 + */ +[LinkName("SDL_scalbn")] public static extern double scalbn(double x, c_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 + */ +[LinkName("SDL_scalbnf")] public static extern float scalbnf(float x, c_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 + */ +[LinkName("SDL_sin")] public static extern double 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 + */ +[LinkName("SDL_sinf")] public static extern float 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 + */ +[LinkName("SDL_sqrt")] public static extern double 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 + */ +[LinkName("SDL_sqrtf")] public static extern float 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 + */ +[LinkName("SDL_tan")] public static extern double 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 + */ +[LinkName("SDL_tanf")] public static extern float 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 + */ +[CRepr] public struct iconv_data_t; public typealias iconv_t = iconv_data_t*; + +/** + * This function allocates a context for the specified character set + * conversion. + * + * \param tocode The target character encoding, must not be NULL. + * \param fromcode The source character encoding, must not be NULL. + * \returns a handle that must be freed with SDL_iconv_close, or + * SDL_ICONV_ERROR on failure. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ +[LinkName("SDL_iconv_open")] public static extern iconv_t iconv_open(c_char* tocode, c_char* fromcode); + +/** + * This function frees a context used for character set conversion. + * + * \param cd The character set conversion handle. + * \returns 0 on success, or -1 on failure. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_open + * \sa SDL_iconv_string + */ +[LinkName("SDL_iconv_close")] public static extern c_int iconv_close(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. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ +[LinkName("SDL_iconv")] public static extern c_size iconv(iconv_t cd, c_char** inbuf, c_size* inbytesleft, c_char** outbuf, c_size* outbytesleft); + +public const let ICONV_ERROR = (c_size)-1;/**< Generic error. Check SDL_GetError()? */ +public const let ICONV_E2BIG = (c_size)-2;/**< Output buffer was too small. */ +public const let ICONV_EILSEQ = (c_size)-3;/**< Invalid input sequence was encountered. */ +public const let ICONV_EINVAL = (c_size)-4;/**< Incomplete input sequence was encountered. */ + + +/** + * Helper function to convert a string's encoding in one call. + * + * This function converts a buffer or string between encodings in one pass. + * + * The string does not need to be NULL-terminated; this function operates on + * the number of bytes specified in `inbytesleft` whether there is a NULL + * character anywhere in the buffer. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param tocode the character encoding of the output string. Examples are + * "UTF-8", "UCS-4", etc. + * \param fromcode the character encoding of data in `inbuf`. + * \param inbuf the string to convert to a different encoding. + * \param inbytesleft the size of the input string _in bytes_. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv + */ +[LinkName("SDL_iconv_string")] public static extern c_char* iconv_string(c_char* tocode, c_char* fromcode, c_char* inbuf, c_size inbytesleft); + +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ + + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ + + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ + + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ + + + +/* force builds using Clang's static analysis tools to use literal C runtime + here, since there are possibly tests that are ineffective otherwise. */ + + +/* The analyzer knows about strlcpy even when the system doesn't provide it */ + + + + +/* The analyzer knows about strlcat even when the system doesn't provide it */ + + + + + + + + + + + + + + + + + +/* 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 */ + + + +/* Starting LLVM 16, the analyser errors out if these functions do not have + their prototype defined (clang-diagnostic-implicit-function-declaration) */ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/** + * 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. + */ +[LinkName("SDL_size_mul_check_overflow")] public static extern bool size_mul_check_overflow(c_size a, c_size b, c_size* ret); + + + + + + + + + + +/* 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. */ +[LinkName("SDL_size_mul_check_overflow_builtin")] public static extern bool size_mul_check_overflow_builtin(c_size a, c_size b, c_size* ret); + + + + + + + +/** + * 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. + */ +[LinkName("SDL_size_add_check_overflow")] public static extern bool size_add_check_overflow(c_size a, c_size b, c_size* ret); + + + + + + + + + + +/* This needs to be wrapped in an inline rather than being a direct #define, + * the same as the call to __builtin_mul_overflow() above. */ +[LinkName("SDL_size_add_check_overflow_builtin")] public static extern bool size_add_check_overflow_builtin(c_size a, c_size b, c_size* ret); + + + + + + + +/* This is a generic function pointer which should be cast to the type you expect */ + + +/** + * 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. + */ + + + + +public function void FunctionPointer(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_stdinc_h_ */ \ No newline at end of file diff --git a/src/SDL_storage.bf b/src/SDL_storage.bf new file mode 100644 index 0000000..ed9fb94 --- /dev/null +++ b/src/SDL_storage.bf @@ -0,0 +1,697 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[CRepr] public struct StorageInterface +{ + /* The version of this interface */ + public Uint32 version; + + /* Called when the storage is closed */ + public function bool(void*) close; + + /* Optional, returns whether the storage is currently ready for access */ + public function bool(void*) ready; + + /* Enumerate a directory, optional for write-only storage */ + public function bool(void*, c_char*, EnumerateDirectoryCallback, void*) enumerate; + + /* Get path information, optional for write-only storage */ + public function bool(void*, c_char*, PathInfo*) info; + + /* Read a file from storage, optional for write-only storage */ + public function bool(void*, c_char*, void*, Uint64) read_file; + + /* Write a file to storage, optional for read-only storage */ + public function bool(void*, c_char*, void*, Uint64) write_file; + + /* Create a directory, optional for read-only storage */ + public function bool(void*, c_char*) mkdir; + + /* Remove a file or empty directory, optional for read-only storage */ + public function bool(void*, c_char*) remove; + + /* Rename a path, optional for read-only storage */ + public function bool(void*, c_char*, c_char*) rename; + + /* Copy a file, optional for read-only storage */ + public function bool(void*, c_char*, c_char*) copy; + + /* Get the space remaining, optional for read-only storage */ + public function Uint64(void* userdata) space_remaining; +} + +/* 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. + */ + + + + +/** + * 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. + */ +[CRepr] public struct 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 + */ +[LinkName("SDL_OpenTitleStorage")] public static extern Storage* OpenTitleStorage(c_char* @override, 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 + */ +[LinkName("SDL_OpenUserStorage")] public static extern Storage* OpenUserStorage(c_char* org, c_char* app, 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 + */ +[LinkName("SDL_OpenFileStorage")] public static extern Storage* OpenFileStorage(c_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 + */ +[LinkName("SDL_OpenStorage")] public static extern Storage* OpenStorage(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 + */ +[LinkName("SDL_CloseStorage")] public static extern bool CloseStorage(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. + */ +[LinkName("SDL_StorageReady")] public static extern bool StorageReady(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 + */ +[LinkName("SDL_GetStorageFileSize")] public static extern bool GetStorageFileSize(Storage* storage, c_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 + */ +[LinkName("SDL_ReadStorageFile")] public static extern bool ReadStorageFile(Storage* storage, c_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 + */ +[LinkName("SDL_WriteStorageFile")] public static extern bool WriteStorageFile(Storage* storage, c_char* path, 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 + */ +[LinkName("SDL_CreateStorageDirectory")] public static extern bool CreateStorageDirectory(Storage* storage, c_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 + */ +[LinkName("SDL_EnumerateStorageDirectory")] public static extern bool EnumerateStorageDirectory(Storage* storage, c_char* path, 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 + */ +[LinkName("SDL_RemoveStoragePath")] public static extern bool RemoveStoragePath(Storage* storage, c_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 + */ +[LinkName("SDL_RenameStoragePath")] public static extern bool RenameStoragePath(Storage* storage, c_char* oldpath, c_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 + */ +[LinkName("SDL_CopyStorageFile")] public static extern bool CopyStorageFile(Storage* storage, c_char* oldpath, c_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 + */ +[LinkName("SDL_GetStoragePathInfo")] public static extern bool GetStoragePathInfo(Storage* storage, c_char* path, out 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 + */ +[LinkName("SDL_GetStorageSpaceRemaining")] public static extern Uint64 GetStorageSpaceRemaining(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. + */ +[LinkName("SDL_GlobStorageDirectory")] public static extern c_char** GlobStorageDirectory(Storage* storage, c_char* path, c_char* pattern, GlobFlags flags, c_int* count); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_storage_h_ */ \ No newline at end of file diff --git a/src/SDL_surface.bf b/src/SDL_surface.bf new file mode 100644 index 0000000..08c49bb --- /dev/null +++ b/src/SDL_surface.bf @@ -0,0 +1,1781 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * The flags on an SDL_Surface. + * + * These are generally considered read-only. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum SurfaceFlags : Uint32 +{ + Preallocated = 0x00000001u, /**< Surface uses preallocated pixel memory */ + LockNeeded = 0x00000002u, /**< Surface needs to be locked to access pixels */ + Locked = 0x00000004u, /**< Surface is currently locked */ + SimdAligned = 0x00000008u, /**< Surface uses pixel memory allocated with SDL_aligned_alloc() */ +} /**< 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. + */ + + +/** + * The scaling mode. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum ScaleMode : c_int +{ + Invalid = -1, + Nearest, /**< nearest pixel sampling */ + Linear, /**< linear filtering */ + Pixelart, /**< nearest pixel sampling with improved scaling for pixel art, available since SDL 3.4.0 */ +} + +/** + * The flip mode. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum FlipMode : c_int +{ + None, /**< Do not flip */ + Horizontal, /**< flip horizontally */ + Vertical, /**< flip vertically */ + HorizontalAndVertical = (Horizontal | Vertical), /**< flip horizontally and vertically (not a diagonal flip) */ +} + + + +/** + * 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 + */ +[CRepr] public struct Surface +{ + public SurfaceFlags flags; /**< The flags of the surface, read-only */ + public PixelFormat format; /**< The format of the surface, read-only */ + public c_int w; /**< The width of the surface, read-only. */ + public c_int h; /**< The height of the surface, read-only. */ + public c_int pitch; /**< The distance in bytes between rows of pixels, read-only */ + public void* pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ + + public c_int refcount; /**< Application reference count, used when freeing surface */ + + public void* reserved; /**< Reserved for internal use */ +} +/* !SDL_INTERNAL */ + + + +/** + * 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 + */ +[LinkName("SDL_CreateSurface")] public static extern Surface* CreateSurface(c_int width, c_int height, 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 + */ +[LinkName("SDL_CreateSurfaceFrom")] public static extern Surface* CreateSurfaceFrom(c_int width, c_int height, PixelFormat format, void* pixels, c_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 + */ +[LinkName("SDL_DestroySurface")] public static extern void DestroySurface(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. + */ +[LinkName("SDL_GetSurfaceProperties")] public static extern PropertiesID GetSurfaceProperties(Surface* surface); + +public const let PROP_SURFACE_SDR_WHITE_POINT_FLOAT = "SDL.surface.SDR_white_point"; +public const let PROP_SURFACE_HDR_HEADROOM_FLOAT = "SDL.surface.HDR_headroom"; +public const let PROP_SURFACE_TONEMAP_OPERATOR_STRING = "SDL.surface.tonemap"; +public const let PROP_SURFACE_HOTSPOT_X_NUMBER = "SDL.surface.hotspot.x"; +public const let PROP_SURFACE_HOTSPOT_Y_NUMBER = "SDL.surface.hotspot.y"; +public const let 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 + */ +[LinkName("SDL_SetSurfaceColorspace")] public static extern bool SetSurfaceColorspace(Surface* surface, 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 + */ +[LinkName("SDL_GetSurfaceColorspace")] public static extern Colorspace GetSurfaceColorspace(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 + */ +[LinkName("SDL_CreateSurfacePalette")] public static extern Palette* CreateSurfacePalette(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 + */ +[LinkName("SDL_SetSurfacePalette")] public static extern bool SetSurfacePalette(Surface* surface, 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 + */ +[LinkName("SDL_GetSurfacePalette")] public static extern Palette* GetSurfacePalette(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 + */ +[LinkName("SDL_AddSurfaceAlternateImage")] public static extern bool AddSurfaceAlternateImage(Surface* surface, 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 + */ +[LinkName("SDL_SurfaceHasAlternateImages")] public static extern bool SurfaceHasAlternateImages(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 + */ +[LinkName("SDL_GetSurfaceImages")] public static extern Surface** GetSurfaceImages(Surface* surface, out c_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 + */ +[LinkName("SDL_RemoveSurfaceAlternateImages")] public static extern void RemoveSurfaceAlternateImages(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 + */ +[LinkName("SDL_LockSurface")] public static extern bool LockSurface(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 + */ +[LinkName("SDL_UnlockSurface")] public static extern void UnlockSurface(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 + */ +[LinkName("SDL_LoadSurface_IO")] public static extern Surface* LoadSurface_IO(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 + */ +[LinkName("SDL_LoadSurface")] public static extern Surface* LoadSurface(c_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 + */ +[LinkName("SDL_LoadBMP_IO")] public static extern Surface* LoadBMP_IO(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 + */ +[LinkName("SDL_LoadBMP")] public static extern Surface* LoadBMP(c_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 + */ +[LinkName("SDL_SaveBMP_IO")] public static extern bool SaveBMP_IO(Surface* surface, 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 + */ +[LinkName("SDL_SaveBMP")] public static extern bool SaveBMP(Surface* surface, c_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 + */ +[LinkName("SDL_LoadPNG_IO")] public static extern Surface* LoadPNG_IO(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 + */ +[LinkName("SDL_LoadPNG")] public static extern Surface* LoadPNG(c_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 + */ +[LinkName("SDL_SavePNG_IO")] public static extern bool SavePNG_IO(Surface* surface, 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 + */ +[LinkName("SDL_SavePNG")] public static extern bool SavePNG(Surface* surface, c_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 + */ +[LinkName("SDL_SetSurfaceRLE")] public static extern bool SetSurfaceRLE(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 + */ +[LinkName("SDL_SurfaceHasRLE")] public static extern bool SurfaceHasRLE(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 + */ +[LinkName("SDL_SetSurfaceColorKey")] public static extern bool SetSurfaceColorKey(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 + */ +[LinkName("SDL_SurfaceHasColorKey")] public static extern bool SurfaceHasColorKey(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 + */ +[LinkName("SDL_GetSurfaceColorKey")] public static extern bool GetSurfaceColorKey(Surface* surface, out 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 + */ +[LinkName("SDL_SetSurfaceColorMod")] public static extern bool SetSurfaceColorMod(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 + */ +[LinkName("SDL_GetSurfaceColorMod")] public static extern bool GetSurfaceColorMod(Surface* surface, out Uint8 r, out Uint8 g, out 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 + */ +[LinkName("SDL_SetSurfaceAlphaMod")] public static extern bool SetSurfaceAlphaMod(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 + */ +[LinkName("SDL_GetSurfaceAlphaMod")] public static extern bool GetSurfaceAlphaMod(Surface* surface, out 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 + */ +[LinkName("SDL_SetSurfaceBlendMode")] public static extern bool SetSurfaceBlendMode(Surface* surface, 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 + */ +[LinkName("SDL_GetSurfaceBlendMode")] public static extern bool GetSurfaceBlendMode(Surface* surface, out 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 + */ +[LinkName("SDL_SetSurfaceClipRect")] public static extern bool SetSurfaceClipRect(Surface* surface, 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 + */ +[LinkName("SDL_GetSurfaceClipRect")] public static extern bool GetSurfaceClipRect(Surface* surface, 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. + */ +[LinkName("SDL_FlipSurface")] public static extern bool FlipSurface(Surface* surface, 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. + */ +[LinkName("SDL_RotateSurface")] public static extern Surface* RotateSurface(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 + */ +[LinkName("SDL_DuplicateSurface")] public static extern Surface* DuplicateSurface(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 + */ +[LinkName("SDL_ScaleSurface")] public static extern Surface* ScaleSurface(Surface* surface, c_int width, c_int height, 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 + */ +[LinkName("SDL_ConvertSurface")] public static extern Surface* ConvertSurface(Surface* surface, 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 + */ +[LinkName("SDL_ConvertSurfaceAndColorspace")] public static extern Surface* ConvertSurfaceAndColorspace(Surface* surface, PixelFormat format, Palette* palette, Colorspace colorspace, 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 + */ +[LinkName("SDL_ConvertPixels")] public static extern bool ConvertPixels(c_int width, c_int height, PixelFormat src_format, void* src, c_int src_pitch, PixelFormat dst_format, void* dst, c_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 + */ +[LinkName("SDL_ConvertPixelsAndColorspace")] public static extern bool ConvertPixelsAndColorspace(c_int width, c_int height, PixelFormat src_format, Colorspace src_colorspace, PropertiesID src_properties, void* src, c_int src_pitch, PixelFormat dst_format, Colorspace dst_colorspace, PropertiesID dst_properties, void* dst, c_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. + */ +[LinkName("SDL_PremultiplyAlpha")] public static extern bool PremultiplyAlpha(c_int width, c_int height, PixelFormat src_format, void* src, c_int src_pitch, PixelFormat dst_format, void* dst, c_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. + */ +[LinkName("SDL_PremultiplySurfaceAlpha")] public static extern bool PremultiplySurfaceAlpha(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. + */ +[LinkName("SDL_ClearSurface")] public static extern bool ClearSurface(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 + */ +[LinkName("SDL_FillSurfaceRect")] public static extern bool FillSurfaceRect(Surface* dst, 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 + */ +[LinkName("SDL_FillSurfaceRects")] public static extern bool FillSurfaceRects(Surface* dst, Rect* rects, c_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 + */ +[LinkName("SDL_BlitSurface")] public static extern bool BlitSurface(Surface* src, Rect* srcrect, Surface* dst, 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 + */ +[LinkName("SDL_BlitSurfaceUnchecked")] public static extern bool BlitSurfaceUnchecked(Surface* src, Rect* srcrect, Surface* dst, 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 + */ +[LinkName("SDL_BlitSurfaceScaled")] public static extern bool BlitSurfaceScaled(Surface* src, Rect* srcrect, Surface* dst, Rect* dstrect, 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 + */ +[LinkName("SDL_BlitSurfaceUncheckedScaled")] public static extern bool BlitSurfaceUncheckedScaled(Surface* src, Rect* srcrect, Surface* dst, Rect* dstrect, 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 + */ +[LinkName("SDL_StretchSurface")] public static extern bool StretchSurface(Surface* src, Rect* srcrect, Surface* dst, Rect* dstrect, 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 + */ +[LinkName("SDL_BlitSurfaceTiled")] public static extern bool BlitSurfaceTiled(Surface* src, Rect* srcrect, Surface* dst, 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 + */ +[LinkName("SDL_BlitSurfaceTiledWithScale")] public static extern bool BlitSurfaceTiledWithScale(Surface* src, Rect* srcrect, float scale, ScaleMode scaleMode, Surface* dst, 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 + */ +[LinkName("SDL_BlitSurface9Grid")] public static extern bool BlitSurface9Grid(Surface* src, Rect* srcrect, c_int left_width, c_int right_width, c_int top_height, c_int bottom_height, float scale, ScaleMode scaleMode, Surface* dst, 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 + */ +[LinkName("SDL_MapSurfaceRGB")] public static extern Uint32 MapSurfaceRGB(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 + */ +[LinkName("SDL_MapSurfaceRGBA")] public static extern Uint32 MapSurfaceRGBA(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. + */ +[LinkName("SDL_ReadSurfacePixel")] public static extern bool ReadSurfacePixel(Surface* surface, c_int x, c_int y, out Uint8 r, out Uint8 g, out Uint8 b, out 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. + */ +[LinkName("SDL_ReadSurfacePixelFloat")] public static extern bool ReadSurfacePixelFloat(Surface* surface, c_int x, c_int y, out float r, out float g, out float b, out 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. + */ +[LinkName("SDL_WriteSurfacePixel")] public static extern bool WriteSurfacePixel(Surface* surface, c_int x, c_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. + */ +[LinkName("SDL_WriteSurfacePixelFloat")] public static extern bool WriteSurfacePixelFloat(Surface* surface, c_int x, c_int y, float r, float g, float b, float a); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_surface_h_ */ \ No newline at end of file diff --git a/src/SDL_system.bf b/src/SDL_system.bf new file mode 100644 index 0000000..da186e9 --- /dev/null +++ b/src/SDL_system.bf @@ -0,0 +1,827 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + + +/* + * Platform specific functions for Windows + */ + + + + +/** + * 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 + */ + + +/** + * Set a callback for every Windows message, run before TranslateMessage(). + * + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. + * + * \param callback the SDL_WindowsMessageHook function to call. + * \param userdata a pointer to pass to every iteration of `callback`. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WindowsMessageHook + * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP + */ + + +/* defined(SDL_PLATFORM_WINDOWS) */ + + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/* 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. */ +[CRepr, Union] public struct _XEvent; public typealias 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 + */ +public function bool X11EventHook(void* userdata, XEvent* xevent); + +/** + * Set a callback for every X11 event. + * + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * \param callback the SDL_X11EventHook function to call. + * \param userdata a pointer to pass to every iteration of `callback`. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_SetX11EventHook")] public static extern void SetX11EventHook(X11EventHook callback, void* userdata); + +/* Platform specific functions for Linux*/ + + +/** + * Sets the UNIX nice value for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID the Unix thread ID to change priority of. + * \param priority the new, Unix-specific, priority value. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ + + +/** + * Sets the priority (not nice level) and scheduling policy for a thread. + * + * This uses setpriority() if possible, and RealtimeKit if available. + * + * \param threadID the Unix thread ID to change priority of. + * \param sdlPriority the new SDL_ThreadPriority value. + * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, + * SCHED_OTHER, etc...). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ + + +/* SDL_PLATFORM_LINUX */ + +/* + * Platform specific functions for 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 + */ + + +/** + * Use this function to set the animation callback on Apple iOS. + * + * The function prototype for `callback` is: + * + * ```c + * void callback(void *callbackParam); + * ``` + * + * Where its parameter, `callbackParam`, is what was passed as `callbackParam` + * to SDL_SetiOSAnimationCallback(). + * + * This function is only available on Apple iOS. + * + * For more information see: + * + * https://wiki.libsdl.org/SDL3/README-ios + * + * Note that if you use the "main callbacks" instead of a standard C `main` + * function, you don't have to use this API, as SDL will manage this for you. + * + * Details on main callbacks are here: + * + * https://wiki.libsdl.org/SDL3/README-main-functions + * + * \param window the window for which the animation callback should be set. + * \param interval the number of frames after which **callback** will be + * called. + * \param callback the function to call for every frame. + * \param callbackParam a pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetiOSEventPump + */ + + +/** + * Use this function to enable or disable the SDL event pump on Apple iOS. + * + * This function is only available on Apple iOS. + * + * \param enabled true to enable the event pump, false to disable it. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetiOSAnimationCallback + */ + + +/* SDL_PLATFORM_IOS */ + + +/* + * Platform specific functions for 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 + */ + + +/** + * 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 + */ + + +/** + * Query Android API level of the current device. + * + * - API level 35: Android 15 (VANILLA_ICE_CREAM) + * - API level 34: Android 14 (UPSIDE_DOWN_CAKE) + * - API level 33: Android 13 (TIRAMISU) + * - API level 32: Android 12L (S_V2) + * - API level 31: Android 12 (S) + * - API level 30: Android 11 (R) + * - API level 29: Android 10 (Q) + * - API level 28: Android 9 (P) + * - API level 27: Android 8.1 (O_MR1) + * - API level 26: Android 8.0 (O) + * - API level 25: Android 7.1 (N_MR1) + * - API level 24: Android 7.0 (N) + * - API level 23: Android 6.0 (M) + * - API level 22: Android 5.1 (LOLLIPOP_MR1) + * - API level 21: Android 5.0 (LOLLIPOP, L) + * - API level 20: Android 4.4W (KITKAT_WATCH) + * - API level 19: Android 4.4 (KITKAT) + * - API level 18: Android 4.3 (JELLY_BEAN_MR2) + * - API level 17: Android 4.2 (JELLY_BEAN_MR1) + * - API level 16: Android 4.1 (JELLY_BEAN) + * - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1) + * - API level 14: Android 4.0 (ICE_CREAM_SANDWICH) + * - API level 13: Android 3.2 (HONEYCOMB_MR2) + * - API level 12: Android 3.1 (HONEYCOMB_MR1) + * - API level 11: Android 3.0 (HONEYCOMB) + * - API level 10: Android 2.3.3 (GINGERBREAD_MR1) + * + * \returns the Android API level. + * + * \since This function is available since SDL 3.2.0. + */ + + +/** + * Query if the application is running on a Chromebook. + * + * \returns true if this is a Chromebook, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ + + +/** + * Query if the application is running on a Samsung DeX docking station. + * + * \returns true if this is a DeX docking station, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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 + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/* SDL_PLATFORM_ANDROID */ + +/** + * Query if the current device is a tablet. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a tablet, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_IsTablet")] public static extern bool IsTablet(); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_IsTV")] public static extern bool IsTV(); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum Sandbox : c_int +{ + None = 0, + UnknownContainer, + Flatpak, + Snap, + Macos, +} + +/** + * 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. + */ +[LinkName("SDL_GetSandbox")] public static extern Sandbox GetSandbox(); + + +/* 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. + */ +[LinkName("SDL_OnApplicationWillTerminate")] public static extern void OnApplicationWillTerminate(); + +/** + * 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. + */ +[LinkName("SDL_OnApplicationDidReceiveMemoryWarning")] public static extern void OnApplicationDidReceiveMemoryWarning(); + +/** + * 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. + */ +[LinkName("SDL_OnApplicationWillEnterBackground")] public static extern void OnApplicationWillEnterBackground(); + +/** + * 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. + */ +[LinkName("SDL_OnApplicationDidEnterBackground")] public static extern void OnApplicationDidEnterBackground(); + +/** + * 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. + */ +[LinkName("SDL_OnApplicationWillEnterForeground")] public static extern void OnApplicationWillEnterForeground(); + +/** + * 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. + */ +[LinkName("SDL_OnApplicationDidEnterForeground")] public static extern void OnApplicationDidEnterForeground(); +} + +/** + * 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. + */ + + + +/* + * Functions used only by GDK + */ + + + + +/** + * 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. + */ + + +/** + * 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. + */ + + + + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_system_h_ */ \ No newline at end of file diff --git a/src/SDL_test.bf b/src/SDL_test.bf new file mode 100644 index 0000000..2ed94be --- /dev/null +++ b/src/SDL_test.bf @@ -0,0 +1,76 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Include file for SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + + + + + + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* Global definitions */ + +/* + * Note: Maximum size of SDLTest log message is less than SDL's limit + * to ensure we can fit additional information such as the timestamp. + */ +public const let SDLTEST_MAX_LOGMESSAGE_LENGTH = 3584; +} + + + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_h_ */ \ No newline at end of file diff --git a/src/SDL_test_assert.bf b/src/SDL_test_assert.bf new file mode 100644 index 0000000..6fa945b --- /dev/null +++ b/src/SDL_test_assert.bf @@ -0,0 +1,104 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Assertion functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + * + * Assert API for test code and test cases + * + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* Fails the assert. */ +public const let ASSERT_FAIL = 0; + +/* Passes the assert. */ +public const let ASSERT_PASS = 1; + +/* + * 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. + */ +[LinkName("SDLTest_Assert")] public static extern void Assert(c_int assertCondition, c_char* assertDescription, ...); + +/* + * 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. + */ +[LinkName("SDLTest_AssertCheck")] public static extern c_int AssertCheck(c_int assertCondition, c_char* assertDescription, ...); + +/* + * Explicitly pass without checking an assertion condition. Updates assertion counter. + * + * \param assertDescription Message to log with the assert describing it. + */ +[LinkName("SDLTest_AssertPass")] public static extern void AssertPass(c_char* assertDescription, ...); + +/* + * Resets the assert summary counters to zero. + */ +[LinkName("SDLTest_ResetAssertSummary")] public static extern void ResetAssertSummary(); + +/* + * Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. + */ +[LinkName("SDLTest_LogAssertSummary")] public static extern void LogAssertSummary(); + +/* + * Converts the current assert summary state to a test result. + * + * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT + */ +[LinkName("SDLTest_AssertSummaryToTestResult")] public static extern c_int AssertSummaryToTestResult(); +} + +/* SDL_test_assert_h_ */ \ No newline at end of file diff --git a/src/SDL_test_common.bf b/src/SDL_test_common.bf new file mode 100644 index 0000000..bd61ba5 --- /dev/null +++ b/src/SDL_test_common.bf @@ -0,0 +1,304 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Common functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* Ported from original test/common.h file. */ + + + + + + + + + + + + + +public const let DEFAULT_WINDOW_WIDTH = 640; +public const let DEFAULT_WINDOW_HEIGHT = 480; + + +public typealias VerboseFlags = Uint32; +public const let VERBOSE_VIDEO = 0x00000001; +public const let VERBOSE_MODES = 0x00000002; +public const let VERBOSE_RENDER = 0x00000004; +public const let VERBOSE_EVENT = 0x00000008; +public const let VERBOSE_AUDIO = 0x00000010; +public const let 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 */ +public function c_int ParseArgumentsFp(void* data, c_char** argv, c_int index); + +/* !< Finalize the argument parser. */ +public function void FinalizeArgumentParserFp(void* arg); + +[CRepr] public struct ArgumentParser +{ + /* !< Parse an argument. */ + public ParseArgumentsFp parse_arguments; + /* !< Finalize this argument parser. Called once before parsing the first argument. */ + public FinalizeArgumentParserFp finalize; + /* !< Null-terminated array of arguments. Printed when running with --help. */ + public c_char** usage; + /* !< User data, passed to all callbacks. */ + public void* data; + /* !< Next argument parser. */ + public ArgumentParser* next; +} + +[CRepr] public struct CommonState +{ + /* SDL init flags */ + public c_char** argv; + public InitFlags flags; + public VerboseFlags verbose; + + /* Video info */ + public c_char* videodriver; + public c_int display_index; + public DisplayID displayID; + public c_char* window_title; + public c_char* window_icon; + public WindowFlags window_flags; + public bool flash_on_focus_loss; + public c_int window_x; + public c_int window_y; + public c_int window_w; + public c_int window_h; + public c_int window_minW; + public c_int window_minH; + public c_int window_maxW; + public c_int window_maxH; + public float window_min_aspect; + public float window_max_aspect; + public c_int logical_w; + public c_int logical_h; + public bool auto_scale_content; + public RendererLogicalPresentation logical_presentation; + public float scale; + public c_int depth; + public float refresh_rate; + public bool fill_usable_bounds; + public bool fullscreen_exclusive; + public DisplayMode fullscreen_mode; + public c_int num_windows; + public Window** windows; + public c_char* gpudriver; + + /* Renderer info */ + public c_char* renderdriver; + public c_int render_vsync; + public bool skip_renderer; + public Renderer** renderers; + public Texture** targets; + + /* Audio info */ + public c_char* audiodriver; + public AudioFormat audio_format; + public c_int audio_channels; + public c_int audio_freq; + public AudioDeviceID audio_id; + + /* GL settings */ + public c_int gl_red_size; + public c_int gl_green_size; + public c_int gl_blue_size; + public c_int gl_alpha_size; + public c_int gl_buffer_size; + public c_int gl_depth_size; + public c_int gl_stencil_size; + public c_int gl_double_buffer; + public c_int gl_accum_red_size; + public c_int gl_accum_green_size; + public c_int gl_accum_blue_size; + public c_int gl_accum_alpha_size; + public c_int gl_stereo; + public c_int gl_release_behavior; + public c_int gl_multisamplebuffers; + public c_int gl_multisamplesamples; + public c_int gl_retained_backing; + public c_int gl_accelerated; + public c_int gl_major_version; + public c_int gl_minor_version; + public c_int gl_debug; + public c_int gl_profile_mask; + + /* Mouse info */ + public Rect confine; + public bool hide_cursor; + + /* Misc. */ + public c_int quit_after_ms_interval; + public TimerID quit_after_ms_timer; + + /* Options info */ + public ArgumentParser common_argparser; + public ArgumentParser video_argparser; + public ArgumentParser audio_argparser; + + public ArgumentParser* argparser; +} + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* Function prototypes */ + +/** + * 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. + */ +[LinkName("SDLTest_CommonCreateState")] public static extern CommonState* CommonCreateState(c_char** argv, InitFlags flags); + +/** + * Free the common state object. + * + * You should call SDL_Quit() before calling this function. + * + * \param state The common state object to destroy + */ +[LinkName("SDLTest_CommonDestroyState")] public static extern void CommonDestroyState(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. + */ +[LinkName("SDLTest_CommonArg")] public static extern c_int CommonArg(CommonState* state, c_int index); + + +/** + * 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. + * This uses the SDL_Log() function and splits up output to be friendly to + * 80-character-wide terminals. + * + * \param state The common state describing the test window for the app. + * \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. + */ +[LinkName("SDLTest_CommonLogUsage")] public static extern void CommonLogUsage(CommonState* state, c_char* argv0, c_char** options); + +/** + * Open test window. + * + * \param state The common state describing the test window to create. + * + * \returns true if initialization succeeded, false otherwise + */ +[LinkName("SDLTest_CommonInit")] public static extern bool CommonInit(CommonState* state); + +/** + * 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 false if app should quit, true otherwise. + */ +[LinkName("SDLTest_CommonDefaultArgs")] public static extern bool CommonDefaultArgs(CommonState* state, c_int argc, c_char** argv); + +/** + * Print the details of an event. + * + * This is automatically called by SDLTest_CommonEvent() as needed. + * + * \param event The event to print. + */ +[LinkName("SDLTest_PrintEvent")] public static extern void PrintEvent(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. + */ +[LinkName("SDLTest_CommonEvent")] public static extern void CommonEvent(CommonState* state, Event* event, c_int* done); + +/** + * Common event handler for test windows if you use SDL_AppEvent. + * + * This does _not_ free anything in `event`. + * + * \param state The common state used to create test window. + * \param event The event to handle. + * \returns Value suitable for returning from SDL_AppEvent(). + */ +[LinkName("SDLTest_CommonEventMainCallbacks")] public static extern AppResult CommonEventMainCallbacks(CommonState* state, Event* event); + +/** + * Close test window. + * + * \param state The common state used to create test window. + * + */ +[LinkName("SDLTest_CommonQuit")] public static extern void CommonQuit(CommonState* state); + +/** + * 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. + * + */ +[LinkName("SDLTest_CommonDrawWindowInfo")] public static extern void CommonDrawWindowInfo(Renderer* renderer, Window* window, float* usedHeight); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_common_h_ */ \ No newline at end of file diff --git a/src/SDL_test_compare.bf b/src/SDL_test_compare.bf new file mode 100644 index 0000000..ad4722b --- /dev/null +++ b/src/SDL_test_compare.bf @@ -0,0 +1,88 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Comparison function of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + + Defines comparison functions (i.e. for surfaces). + +*/ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * Compares a surface and with reference image data for equality + * + * \param surface Surface used in comparison + * \param referenceSurface Test Surface used in comparison + * \param allowable_error Allowable difference (=sum of squared difference for each RGB component) in blending accuracy. + * + * \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. + */ +[LinkName("SDLTest_CompareSurfaces")] public static extern c_int CompareSurfaces(Surface* surface, Surface* referenceSurface, c_int allowable_error); +[LinkName("SDLTest_CompareSurfacesIgnoreTransparentPixels")] public static extern c_int CompareSurfacesIgnoreTransparentPixels(Surface* surface, Surface* referenceSurface, c_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. + */ +[LinkName("SDLTest_CompareMemory")] public static extern c_int CompareMemory(void* actual, c_size size_actual, void* reference, c_size size_reference); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_compare_h_ */ \ No newline at end of file diff --git a/src/SDL_test_crc32.bf b/src/SDL_test_crc32.bf new file mode 100644 index 0000000..13b7b2f --- /dev/null +++ b/src/SDL_test_crc32.bf @@ -0,0 +1,132 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * CRC32 functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + + Implements CRC32 calculations (default output is Perl String::CRC32 compatible). + +*/ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* ------------ Definitions --------- */ + +/* Definition shared by all CRC routines */ + + + + + + + + + + /* AUTODIN II, Ethernet, & FDDI */ + + public const let CRC32_POLY = 0xEDB88320; /* Perl String::CRC32 compatible */ + + +/* + * Data structure for CRC32 (checksum) computation + */ + [CRepr] public struct Crc32Context { + public Uint32[256] crc32_table; /* CRC table */ + } + +/* ---------- Function Prototypes ------------- */ + +/* + * Initialize the CRC context + * + * Note: The function initializes the crc table required for all crc calculations. + * + * \param crcContext pointer to context variable + * + * \returns true on success or false on failure; call SDL_GetError() + * for more information. + * + */ +[LinkName("SDLTest_Crc32Init")] public static extern bool Crc32Init(Crc32Context* crcContext); + +/* + * 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 true on success or false on failure; call SDL_GetError() + * for more information. + * + */ +[LinkName("SDLTest_Crc32Calc")] public static extern bool Crc32Calc(Crc32Context* crcContext, Uint8* inBuf, Uint32 inLen, Uint32* crc32); + +/* Same routine broken down into three steps */ +[LinkName("SDLTest_Crc32CalcStart")] public static extern bool Crc32CalcStart(Crc32Context* crcContext, Uint32* crc32); +[LinkName("SDLTest_Crc32CalcEnd")] public static extern bool Crc32CalcEnd(Crc32Context* crcContext, Uint32* crc32); +[LinkName("SDLTest_Crc32CalcBuffer")] public static extern bool Crc32CalcBuffer(Crc32Context* crcContext, Uint8* inBuf, Uint32 inLen, Uint32* crc32); + +/* + * clean up CRC context + * + * \param crcContext pointer to context variable + * + * \returns true on success or false on failure; call SDL_GetError() + * for more information. + * +*/ + +[LinkName("SDLTest_Crc32Done")] public static extern bool Crc32Done(Crc32Context* crcContext); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_crc32_h_ */ \ No newline at end of file diff --git a/src/SDL_test_font.bf b/src/SDL_test_font.bf new file mode 100644 index 0000000..3d17787 --- /dev/null +++ b/src/SDL_test_font.bf @@ -0,0 +1,180 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/* + * Font related functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* Function prototypes */ + +[CLink] public static extern c_int FONT_CHARACTER_SIZE; + +public static c_int FONT_LINE_HEIGHT => (FONT_CHARACTER_SIZE + 2); + +/* + * 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 true on success, false on failure. + */ +[LinkName("SDLTest_DrawCharacter")] public static extern bool DrawCharacter(Renderer* renderer, float x, float y, Uint32 c); + +/* + * 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. + * + * \param renderer The renderer to draw on. + * \param x The X coordinate of the upper left corner of the string. + * \param y The Y coordinate of the upper left corner of the string. + * \param s The string to draw. + * + * \returns true on success, false on failure. + */ +[LinkName("SDLTest_DrawString")] public static extern bool DrawString(Renderer* renderer, float x, float y, c_char* s); + +/* + * Data used for multi-line text output + */ +[CRepr] public struct TextWindow +{ + public FRect rect; + public c_int current; + public c_int numlines; + public c_char** lines; +} + +/* + * 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. + * \param w The width of the window (currently ignored) + * \param h The height of the window (currently ignored) + * + * \returns the new window, or NULL on failure. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDLTest_TextWindowCreate")] public static extern TextWindow* TextWindowCreate(float x, float y, float w, float h); + +/* + * 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 3.2.0. + */ +[LinkName("SDLTest_TextWindowDisplay")] public static extern void TextWindowDisplay(TextWindow* textwin, Renderer* renderer); + +/* + * 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 + * line is empty, deletes the line and goes to the end of the previous line. + * + * \param textwin The text output window + * \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 3.2.0. + */ +[LinkName("SDLTest_TextWindowAddText")] public static extern void TextWindowAddText(TextWindow* textwin, c_char* fmt, ...); + +/* + * 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 + * line is empty, deletes the line and goes to the end of the previous line. + * + * \param textwin The text output window + * \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 3.2.0. + */ +[LinkName("SDLTest_TextWindowAddTextWithLength")] public static extern void TextWindowAddTextWithLength(TextWindow* textwin, c_char* text, c_size len); + +/* + * Clear the text in a multi-line text output window + * + * \param textwin The text output window + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDLTest_TextWindowClear")] public static extern void TextWindowClear(TextWindow* textwin); + +/* + * Free the storage associated with a multi-line text output window + * + * \param textwin The text output window + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDLTest_TextWindowDestroy")] public static extern void TextWindowDestroy(TextWindow* textwin); + +/* + * Cleanup textures used by font drawing functions. + */ +[LinkName("SDLTest_CleanupTextDrawing")] public static extern void CleanupTextDrawing(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_font_h_ */ \ No newline at end of file diff --git a/src/SDL_test_fuzzer.bf b/src/SDL_test_fuzzer.bf new file mode 100644 index 0000000..43374a8 --- /dev/null +++ b/src/SDL_test_fuzzer.bf @@ -0,0 +1,382 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Fuzzer functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + + Data generators for fuzzing test data in a reproducible way. + +*/ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* + Based on GSOC code by Markus Kauppila +*/ + +/** + * 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. + * + */ +[LinkName("SDLTest_FuzzerInit")] public static extern void FuzzerInit(Uint64 execKey); + +/** + * Returns a random Uint8 + * + * \returns a generated integer + */ +[LinkName("SDLTest_RandomUint8")] public static extern Uint8 RandomUint8(); + +/** + * Returns a random Sint8 + * + * \returns a generated signed integer + */ +[LinkName("SDLTest_RandomSint8")] public static extern Sint8 RandomSint8(); + +/** + * Returns a random Uint16 + * + * \returns a generated integer + */ +[LinkName("SDLTest_RandomUint16")] public static extern Uint16 RandomUint16(); + +/** + * Returns a random Sint16 + * + * \returns a generated signed integer + */ +[LinkName("SDLTest_RandomSint16")] public static extern Sint16 RandomSint16(); + +/** + * Returns a random integer + * + * \returns a generated integer + */ +[LinkName("SDLTest_RandomSint32")] public static extern Sint32 RandomSint32(); + +/** + * Returns a random positive integer + * + * \returns a generated integer + */ +[LinkName("SDLTest_RandomUint32")] public static extern Uint32 RandomUint32(); + +/** + * Returns random Uint64. + * + * \returns a generated integer + */ +[LinkName("SDLTest_RandomUint64")] public static extern Uint64 RandomUint64(); + +/** + * Returns random Sint64. + * + * \returns a generated signed integer + */ +[LinkName("SDLTest_RandomSint64")] public static extern Sint64 RandomSint64(); + +/** + * \returns a random float in range [0.0 - 1.0] + */ +[LinkName("SDLTest_RandomUnitFloat")] public static extern float RandomUnitFloat(); + +/** + * \returns a random double in range [0.0 - 1.0] + */ +[LinkName("SDLTest_RandomUnitDouble")] public static extern double RandomUnitDouble(); + +/** + * \returns a random float. + * + */ +[LinkName("SDLTest_RandomFloat")] public static extern float RandomFloat(); + +/** + * \returns a random double. + * + */ +[LinkName("SDLTest_RandomDouble")] public static extern double RandomDouble(); + +/** + * 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or 0 with error set + */ +[LinkName("SDLTest_RandomUint8BoundaryValue")] public static extern Uint8 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or 0 with error set + */ +[LinkName("SDLTest_RandomUint16BoundaryValue")] public static extern Uint16 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or 0 with error set + */ +[LinkName("SDLTest_RandomUint32BoundaryValue")] public static extern Uint32 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or 0 with error set + */ +[LinkName("SDLTest_RandomUint64BoundaryValue")] public static extern Uint64 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or SINT8_MIN with error set + */ +[LinkName("SDLTest_RandomSint8BoundaryValue")] public static extern Sint8 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or SINT16_MIN with error set + */ +[LinkName("SDLTest_RandomSint16BoundaryValue")] public static extern Sint16 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or SINT32_MIN with error set + */ +[LinkName("SDLTest_RandomSint32BoundaryValue")] public static extern Sint32 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 + * boundaries are also possible. + * If boundary1 > boundary2, the values are swapped + * + * Usage examples: + * 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 + * \param validDomain Should the generated boundary be valid (=within the bounds) or not? + * + * \returns a random boundary value for the given range and domain or SINT64_MIN with error set + */ +[LinkName("SDLTest_RandomSint64BoundaryValue")] public static extern Sint64 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. + * Min and max are the same value, that value will be returned. + * + * \param min Minimum inclusive value of returned random number + * \param max Maximum inclusive value of returned random number + * + * \returns a generated random integer in range + */ +[LinkName("SDLTest_RandomIntegerInRange")] public static extern Sint32 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. + * + * Note: Returned string needs to be deallocated. + * + * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated. + */ +[LinkName("SDLTest_RandomAsciiString")] public static extern c_char* RandomAsciiString(); + +/** + * 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. + * + * Note: Returned string needs to be deallocated. + * + * \param maxLength The maximum length of the generated string. + * + * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated. + */ +[LinkName("SDLTest_RandomAsciiStringWithMaximumLength")] public static extern c_char* RandomAsciiStringWithMaximumLength(c_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. + * + * Note: Returned string needs to be deallocated. + * + * \param size The length of the generated string + * + * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated. + */ +[LinkName("SDLTest_RandomAsciiStringOfSize")] public static extern c_char* RandomAsciiStringOfSize(c_int size); + +/** + * Get the invocation count for the fuzzer since last ...FuzzerInit. + * + * \returns the invocation count. + */ +[LinkName("SDLTest_GetFuzzerInvocationCount")] public static extern c_int GetFuzzerInvocationCount(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_fuzzer_h_ */ \ No newline at end of file diff --git a/src/SDL_test_harness.bf b/src/SDL_test_harness.bf new file mode 100644 index 0000000..308f628 --- /dev/null +++ b/src/SDL_test_harness.bf @@ -0,0 +1,162 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Test suite related functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + Defines types for test case definitions and the test execution harness API. + + Based on original GSOC code by Markus Kauppila +*/ + + + + + +/* SDLTest_CommonState */ + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* ! Definitions for test case structures */ +public const let TEST_ENABLED = 1; +public const let TEST_DISABLED = 0; + +/* ! Definition of all the possible test return values of the test case method */ +public const let TEST_ABORTED = -1; +public const let TEST_STARTED = 0; +public const let TEST_COMPLETED = 1; +public const let TEST_SKIPPED = 2; + +/* ! Definition of all the possible test results for the harness */ +public const let TEST_RESULT_PASSED = 0; +public const let TEST_RESULT_FAILED = 1; +public const let TEST_RESULT_NO_ASSERT = 2; +public const let TEST_RESULT_SKIPPED = 3; +public const let TEST_RESULT_SETUP_FAILURE = 4; + +/* !< Function pointer to a test case setup function (run before every test) */ +public function void TestCaseSetUpFp(void** arg); + +/* !< Function pointer to a test case function */ +public function c_int TestCaseFp(void* arg); + +/* !< Function pointer to a test case teardown function (run after every test) */ +public function void TestCaseTearDownFp(void* arg); + +/* + * Holds information about a single test case. + */ +[CRepr] public struct TestCaseReference { + /* !< Func2Stress */ + public TestCaseFp testCase; + /* !< Short name (or function name) "Func2Stress" */ + public c_char* name; + /* !< Long name or full description "This test pushes func2() to the limit." */ + public c_char* description; + /* !< Set to TEST_ENABLED or TEST_DISABLED (test won't be run) */ + public c_int enabled; +} + +/* + * Holds information about a test suite (multiple test cases). + */ +[CRepr] public struct TestSuiteReference { + /* !< "PlatformSuite" */ + public c_char* name; + /* !< The function that is run before each test. NULL skips. */ + public TestCaseSetUpFp testSetUp; + /* !< The test cases that are run as part of the suite. Last item should be NULL. */ + public TestCaseReference** testCases; + /* !< The function that is run after each test. NULL skips. */ + public TestCaseTearDownFp testTearDown; +} + + +/* + * Generates a random run seed string for the harness. The generated seed + * will contain alphanumeric characters (0-9A-Z). + * + * \param buffer Buffer in which to generate the random seed. Must have a capacity of at least length + 1 characters. + * \param length Number of alphanumeric characters to write to buffer, must be >0 + * + * \returns A null-terminated seed string and equal to the in put buffer on success, NULL on failure + */ +[LinkName("SDLTest_GenerateRunSeed")] public static extern c_char* GenerateRunSeed(c_char* buffer, c_int length); + +/* + * Holds information about the execution of test suites. + * */ +[CRepr] public struct 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 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. + */ +[LinkName("SDLTest_CreateTestSuiteRunner")] public static extern TestSuiteRunner* CreateTestSuiteRunner(CommonState* state, 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. + */ +[LinkName("SDLTest_DestroyTestSuiteRunner")] public static extern void DestroyTestSuiteRunner(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. + */ +[LinkName("SDLTest_ExecuteTestSuiteRunner")] public static extern c_int ExecuteTestSuiteRunner(TestSuiteRunner* runner); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_h_arness_h */ \ No newline at end of file diff --git a/src/SDL_test_log.bf b/src/SDL_test_log.bf new file mode 100644 index 0000000..040a6cf --- /dev/null +++ b/src/SDL_test_log.bf @@ -0,0 +1,94 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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 + * + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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 + */ +[LinkName("SDLTest_LogMessage")] public static extern void LogMessage(LogPriority priority, c_char* fmt, ...); + +/** + * Prints given message with a timestamp in the TEST category and INFO priority. + * + * \param fmt Message to be logged + */ +[LinkName("SDLTest_Log")] public static extern void Log(c_char* fmt, ...); + +/** + * 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. + */ +[LinkName("SDLTest_LogEscapedString")] public static extern void LogEscapedString(c_char* prefix, void* buffer, c_size size); + +/** + * Prints given message with a timestamp in the TEST category and the ERROR priority. + * + * \param fmt Message to be logged + */ +[LinkName("SDLTest_LogError")] public static extern void LogError(c_char* fmt, ...); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_log_h_ */ \ No newline at end of file diff --git a/src/SDL_test_md5.bf b/src/SDL_test_md5.bf new file mode 100644 index 0000000..35f96ee --- /dev/null +++ b/src/SDL_test_md5.bf @@ -0,0 +1,132 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * MD5 related functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + +/* + *********************************************************************** + ** Header file for implementation of MD5 ** + ** RSA Data Security, Inc. MD5 Message-Digest Algorithm ** + ** Created: 2/17/90 RLR ** + ** Revised: 12/27/90 SRD,AJ,BSK,JT Reference C version ** + ** Revised (for MD5): RLR 4/27/91 ** + ** -- G modified to have y&~z instead of y&z ** + ** -- FF, GG, HH modified to add in last register done ** + ** -- Access pattern: round 2 works mod 5, round 3 works mod 3 ** + ** -- distinct additive constant for each step ** + ** -- round 4 added, working mod 7 ** + *********************************************************************** +*/ + +/* + *********************************************************************** + ** Message-digest routines: ** + ** To form the message digest for a message M ** + ** (1) Initialize a context buffer mdContext using MD5Init ** + ** (2) Call MD5Update on mdContext and M ** + ** (3) Call MD5Final on mdContext ** + ** The message digest is now in mdContext->digest[0...15] ** + *********************************************************************** +*/ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* ------------ Definitions --------- */ + +/* typedef a 32-bit type */ +public typealias MD5UINT4 = Uint32; + +/* Data structure for MD5 (Message-Digest) computation */ +[CRepr] public struct Md5Context { + public MD5UINT4[2] i; /* number of _bits_ handled mod 2^64 */ + public MD5UINT4[4] buf; /* scratch buffer */ + public c_uchar[64] @in; /* input buffer */ + public c_uchar[16] digest; /* actual digest after Md5Final call */ +} + +/* ---------- Function Prototypes ------------- */ + +/** + * initialize the context + * + * \param mdContext pointer to context variable + * + * Note: The function initializes the message-digest context + * mdContext. Call before each new use of the context - + * all fields are set to zero. + */ +[LinkName("SDLTest_Md5Init")] public static extern void Md5Init(Md5Context* mdContext); + +/** + * update digest from variable length data + * + * \param mdContext pointer to context variable + * \param inBuf pointer to data array/string + * \param inLen length of data array/string + * + * 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. + */ +[LinkName("SDLTest_Md5Update")] public static extern void Md5Update(Md5Context* mdContext, c_uchar* inBuf, c_uint inLen); + +/** + * 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. + */ +[LinkName("SDLTest_Md5Final")] public static extern void Md5Final(Md5Context* mdContext); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_md5_h_ */ \ No newline at end of file diff --git a/src/SDL_test_memory.bf b/src/SDL_test_memory.bf new file mode 100644 index 0000000..7b08606 --- /dev/null +++ b/src/SDL_test_memory.bf @@ -0,0 +1,77 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDLTest +{ +/* + 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. +*/ + +/** + * Memory tracking related functions of SDL test framework. + * + * This code is a part of the SDL test library, not the main SDL library. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * Start tracking SDL memory allocations + * + * \note This should be called before any other SDL functions for complete tracking coverage + */ +[LinkName("SDLTest_TrackAllocations")] public static extern void TrackAllocations(); + +/** + * Fill allocations with random data + * + * \note This implicitly calls SDLTest_TrackAllocations() + */ +[LinkName("SDLTest_RandFillAllocations")] public static extern void RandFillAllocations(); + +/** + * Print a log of any outstanding allocations + * + * \note This can be called after SDL_Quit() + */ +[LinkName("SDLTest_LogAllocations")] public static extern void LogAllocations(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_test_memory_h_ */ \ No newline at end of file diff --git a/src/SDL_thread.bf b/src/SDL_thread.bf new file mode 100644 index 0000000..8b778bc --- /dev/null +++ b/src/SDL_thread.bf @@ -0,0 +1,590 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + + + + +/** + * # 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. + */ + + + + + +/* Thread synchronization primitives */ + + + +/* _beginthreadex() and _endthreadex() */ + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * The SDL thread object. + * + * These are opaque data. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ +[CRepr] public struct 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 + */ +public typealias ThreadID = Uint64; + +/** + * 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 + */ +public typealias TLSID = AtomicInt; + +/** + * 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. + */ +[AllowDuplicates] public enum ThreadPriority : c_int { + Low, + Normal, + High, + TimeCritical, +} + +/** + * 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 + */ +[AllowDuplicates] public enum ThreadState : c_int +{ + Unknown, /**< The thread is not valid */ + Alive, /**< The thread is currently running */ + Detached, /**< The thread is detached and can't be waited on */ + Complete, /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} + +/** + * 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. + */ +public function c_int ThreadFunction(void* data); + + + + +/* + * Note that these aren't the correct function signatures in this block, but + * this is what the API reference manual should look like for all intents and + * purposes. + * + * Technical details, not for the wiki (hello, header readers!)... + * + * On Windows (and maybe other platforms), a program might use a different + * C runtime than its libraries. Or, in SDL's case, it might use a C runtime + * while SDL uses none at all. + * + * C runtimes expect to initialize thread-specific details when a new thread + * is created, but to do this in SDL_CreateThread would require SDL to know + * intimate details about the caller's C runtime, which is not possible. + * + * So SDL_CreateThread has two extra parameters, which are + * hidden at compile time by macros: the C runtime's `_beginthreadex` and + * `_endthreadex` entry points. If these are not NULL, they are used to spin + * and terminate the new thread; otherwise the standard Win32 `CreateThread` + * function is used. When `SDL_CreateThread` is called from a compiler that + * needs this C runtime thread init function, macros insert the appropriate + * function pointers for SDL_CreateThread's caller (which might be a different + * compiler with a different runtime in different calls to SDL_CreateThread!). + * + * SDL_BeginThreadFunction defaults to `_beginthreadex` on Windows (and NULL + * everywhere else), but apps that have extremely specific special needs can + * define this to something else and the SDL headers will use it, passing the + * app-defined value to SDL_CreateThread calls. Redefine this with caution! + * + * Platforms that don't need _beginthread stuff (most everything) will fail + * SDL_CreateThread with an error if these pointers _aren't_ NULL. + * + * Unless you are doing something extremely complicated, like perhaps a + * language binding, **you should never deal with this directly**. Let SDL's + * macros handle this platform-specific detail transparently! + */ + +/** + * Create a new thread with a default stack size. + * + * This is a convenience function, equivalent to calling + * SDL_CreateThreadWithProperties with the following properties set: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: `fn` + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: `name` + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: `data` + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param fn the SDL_ThreadFunction function to call in the new thread. + * \param name the name of the thread. + * \param data a pointer that is passed to `fn`. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThreadWithProperties + * \sa SDL_WaitThread + */ + + +/** + * Create a new thread with with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: an SDL_ThreadFunction + * value that will be called at the start of the new thread's life. + * Required. + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: the name of the new thread, which + * might be available to debuggers. Optional, defaults to NULL. + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: an arbitrary app-defined + * pointer, which is passed to the entry function on the new thread, as its + * only parameter. Optional, defaults to NULL. + * - `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`: the size, in bytes, of the new + * thread's stack. Optional, defaults to 0 (system-defined default). + * + * SDL makes an attempt to report `SDL_PROP_THREAD_CREATE_NAME_STRING` to the + * system, so that debuggers can display it. Not all platforms support this. + * + * Thread naming is a little complicated: Most systems have very small limits + * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual + * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to + * see what happens with your system's debugger. The name should be UTF-8 (but + * using the naming limits of C identifiers is a better bet). There are no + * requirements for thread naming conventions, so long as the string is + * null-terminated UTF-8, but these guidelines are helpful in choosing a name: + * + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for it + * (truncate, etc), but the original string contents will be available from + * SDL_GetThreadName(). + * + * The size (in bytes) of the new stack can be specified with + * `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`. Zero means "use the system + * default" which might be wildly different between platforms. x86 Linux + * generally defaults to eight megabytes, an embedded device might be a few + * kilobytes instead. You generally need to specify a stack that is a multiple + * of the system's page size (in many cases, this is 4 kilobytes, but check + * your system documentation). + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * The actual symbol in SDL is `SDL_CreateThreadWithPropertiesRuntime`, so + * there is no symbol clash, but trying to load an SDL shared library and look + * for "SDL_CreateThreadWithProperties" will fail. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param props the properties to use. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ + + + + + + + +/* end wiki documentation for macros that are meant to look like functions. */ + + + +/* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ + + + + + + + + + + + +/* currently no other platforms than Windows use _beginthreadex/_endthreadex things. */ + + +public const let BeginThreadFunction = null; + + + + + +public const let EndThreadFunction = null; + + + + +/* These are the actual functions exported from SDL! Don't use them directly! Use the SDL_CreateThread and SDL_CreateThreadWithProperties macros! */ +/** + * The actual entry point for SDL_CreateThread. + * + * \param fn the SDL_ThreadFunction function to call in the new thread + * \param name the name of the thread + * \param data a pointer that is passed to `fn` + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be NULL. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be NULL. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_CreateThreadRuntime")] public static extern Thread* CreateThreadRuntime(ThreadFunction fn, c_char* name, void* data, FunctionPointer pfnBeginThread, FunctionPointer pfnEndThread); + +/** + * The actual entry point for SDL_CreateThreadWithProperties. + * + * \param props the properties to use + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be NULL. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be NULL. + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_CreateThreadWithPropertiesRuntime")] public static extern Thread* CreateThreadWithPropertiesRuntime(PropertiesID props, FunctionPointer pfnBeginThread, FunctionPointer pfnEndThread); + + + +public const let PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER = "SDL.thread.create.entry_function"; +public const let PROP_THREAD_CREATE_NAME_STRING = "SDL.thread.create.name"; +public const let PROP_THREAD_CREATE_USERDATA_POINTER = "SDL.thread.create.userdata"; +public const let PROP_THREAD_CREATE_STACKSIZE_NUMBER = "SDL.thread.create.stacksize"; + + + +/** + * Get the thread name as it was specified in SDL_CreateThread(). + * + * \param thread the thread to query. + * \returns a pointer to a UTF-8 string that names the specified thread, or + * NULL if it doesn't have a name. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetThreadName")] public static extern c_char* GetThreadName(Thread* thread); + +/** + * Get the thread identifier for the current thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * This function also returns a valid thread ID when called from the main + * thread. + * + * \returns the ID of the current thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetThreadID + */ +[LinkName("SDL_GetCurrentThreadID")] public static extern ThreadID GetCurrentThreadID(); + +/** + * Get the thread identifier for the specified thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * \param thread the thread to query. + * \returns the ID of the specified thread, or the ID of the current thread if + * `thread` is NULL. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentThreadID + */ +[LinkName("SDL_GetThreadID")] public static extern ThreadID GetThreadID(Thread* thread); + +/** + * Set the priority for the current thread. + * + * Note that some platforms will not let you alter the priority (or at least, + * promote the thread to a higher priority) at all, and some require you to be + * an administrator account. Be prepared for this to fail. + * + * \param priority the SDL_ThreadPriority to set. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_SetCurrentThreadPriority")] public static extern bool SetCurrentThreadPriority(ThreadPriority priority); + +/** + * Wait for a thread to finish. + * + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. As + * such, only one thread may call SDL_WaitThread() on another. + * + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not both, or + * behavior is undefined. + * + * It is safe to pass a NULL thread to this function; it is a no-op. + * + * Note that the thread pointer is freed by this function and is not valid + * afterward. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_DetachThread + */ +[LinkName("SDL_WaitThread")] public static extern void WaitThread(Thread* thread, out c_int status); + +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +[LinkName("SDL_GetThreadState")] public static extern ThreadState GetThreadState(Thread* thread); + +/** + * Let a thread clean up on exit without intervention. + * + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread is + * useful for long-running threads that nothing needs to synchronize with or + * further manage. When a detached thread is done, it simply goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon the + * detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is + * not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. Use + * either that function or this one, but not both, or behavior is undefined. + * + * It is safe to pass NULL to this function; it is a no-op. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + */ +[LinkName("SDL_DetachThread")] public static extern void DetachThread(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 + */ +[LinkName("SDL_GetTLS")] public static extern void* GetTLS(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 + */ +public function void 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 + */ +[LinkName("SDL_SetTLS")] public static extern bool SetTLS(TLSID* id, void* value, 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. + */ +[LinkName("SDL_CleanupTLS")] public static extern void CleanupTLS(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_thread_h_ */ \ No newline at end of file diff --git a/src/SDL_time.bf b/src/SDL_time.bf new file mode 100644 index 0000000..0d498c0 --- /dev/null +++ b/src/SDL_time.bf @@ -0,0 +1,242 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* +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. +*/ + + + + +/** + * # 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. + */ + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * A structure holding a calendar date and time broken down into its + * components. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct DateTime +{ + public c_int year; /**< Year */ + public c_int month; /**< Month [01-12] */ + public c_int day; /**< Day of the month [01-31] */ + public c_int hour; /**< Hour [0-23] */ + public c_int minute; /**< Minute [0-59] */ + public c_int second; /**< Seconds [0-60] */ + public c_int nanosecond; /**< Nanoseconds [0-999999999] */ + public c_int day_of_week; /**< Day of the week [0-6] (0 being Sunday) */ + public c_int utc_offset; /**< Seconds east of UTC */ +} + +/** + * The preferred date format of the current system locale. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetDateTimeLocalePreferences + */ +[AllowDuplicates] public enum DateFormat : c_int +{ + Yyyymmdd = 0, /**< Year/Month/Day */ + Ddmmyyyy = 1, /**< Day/Month/Year */ + Mmddyyyy = 2, /**< Month/Day/Year */ +} + +/** + * The preferred time format of the current system locale. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetDateTimeLocalePreferences + */ +[AllowDuplicates] public enum TimeFormat : c_int +{ + _24hr = 0, /**< 24 hour time */ + _12hr = 1, /**< 12 hour time */ +} + +/** + * Gets the current preferred date and time format for the system locale. + * + * This might be a "slow" call that has to query the operating system. It's + * best to ask for this once and save the results. However, the preferred + * formats can change, usually because the user has changed a system + * preference outside of your program. + * + * \param dateFormat a pointer to the SDL_DateFormat to hold the returned date + * format, may be NULL. + * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time + * format, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetDateTimeLocalePreferences")] public static extern bool GetDateTimeLocalePreferences(DateFormat* dateFormat, TimeFormat* timeFormat); + +/** + * Gets the current value of the system realtime clock in nanoseconds since + * Jan 1, 1970 in Universal Coordinated Time (UTC). + * + * \param ticks the SDL_Time to hold the returned tick count. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetCurrentTime")] public static extern bool GetCurrentTime(Time* ticks); + +/** + * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in + * the SDL_DateTime format. + * + * \param ticks the SDL_Time to be converted. + * \param dt the resulting SDL_DateTime. + * \param localTime the resulting SDL_DateTime will be expressed in local time + * if true, otherwise it will be in Universal Coordinated + * Time (UTC). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_TimeToDateTime")] public static extern bool TimeToDateTime(Time ticks, DateTime* dt, bool localTime); + +/** + * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. + * + * This function ignores the day_of_week member of the SDL_DateTime struct, so + * it may remain unset. + * + * \param dt the source SDL_DateTime. + * \param ticks the resulting SDL_Time. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_DateTimeToTime")] public static extern bool DateTimeToTime(DateTime* dt, Time* ticks); + +/** + * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals + * since January 1, 1601). + * + * This function fills in the two 32-bit values of the FILETIME structure. + * + * \param ticks the time to convert. + * \param dwLowDateTime a pointer filled in with the low portion of the + * Windows FILETIME value. + * \param dwHighDateTime a pointer filled in with the high portion of the + * Windows FILETIME value. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_TimeToWindows")] public static extern void TimeToWindows(Time ticks, out Uint32 dwLowDateTime, out Uint32 dwHighDateTime); + +/** + * Converts a Windows FILETIME (100-nanosecond intervals since January 1, + * 1601) to an SDL time. + * + * This function takes the two 32-bit values of the FILETIME structure as + * parameters. + * + * \param dwLowDateTime the low portion of the Windows FILETIME value. + * \param dwHighDateTime the high portion of the Windows FILETIME value. + * \returns the converted SDL time. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_TimeFromWindows")] public static extern Time TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); + +/** + * Get the number of days in a month for a given year. + * + * \param year the year. + * \param month the month [1-12]. + * \returns the number of days in the requested month or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetDaysInMonth")] public static extern c_int GetDaysInMonth(c_int year, c_int month); + +/** + * Get the day of year for a calendar date. + * + * \param year the year component of the date. + * \param month the month component of the date. + * \param day the day component of the date. + * \returns the day of year [0-365] if the date is valid or -1 on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetDayOfYear")] public static extern c_int GetDayOfYear(c_int year, c_int month, c_int day); + +/** + * Get the day of week for a calendar date. + * + * \param year the year component of the date. + * \param month the month component of the date. + * \param day the day component of the date. + * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or + * -1 on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + */ +[LinkName("SDL_GetDayOfWeek")] public static extern c_int GetDayOfWeek(c_int year, c_int month, c_int day); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_time_h_ */ \ No newline at end of file diff --git a/src/SDL_timer.bf b/src/SDL_timer.bf new file mode 100644 index 0000000..3043d8e --- /dev/null +++ b/src/SDL_timer.bf @@ -0,0 +1,464 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. +*/ + + + + +/** + * # 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. + */ + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let MS_PER_SECOND = 1000; + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let US_PER_SECOND = 1000000; + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let NS_PER_SECOND = 1000000000L; + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let NS_PER_MS = 1000000; + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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. + */ + + +/** + * 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 + */ +[LinkName("SDL_GetTicks")] public static extern Uint64 GetTicks(); + +/** + * 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. + */ +[LinkName("SDL_GetTicksNS")] public static extern Uint64 GetTicksNS(); + +/** + * 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 + */ +[LinkName("SDL_GetPerformanceCounter")] public static extern Uint64 GetPerformanceCounter(); + +/** + * 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 + */ +[LinkName("SDL_GetPerformanceFrequency")] public static extern Uint64 GetPerformanceFrequency(); + +/** + * 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 + */ +[LinkName("SDL_Delay")] public static extern void 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 + */ +[LinkName("SDL_DelayNS")] public static extern void 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 + */ +[LinkName("SDL_DelayPrecise")] public static extern void DelayPrecise(Uint64 ns); + +/** + * Definition of the timer ID type. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias TimerID = Uint32; + +/** + * 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 + */ +public function Uint32 TimerCallback(void* userdata, 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 + */ +[LinkName("SDL_AddTimer")] public static extern TimerID AddTimer(Uint32 interval, 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 + */ +public function Uint64 NSTimerCallback(void* userdata, 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 + */ +[LinkName("SDL_AddTimerNS")] public static extern TimerID AddTimerNS(Uint64 interval, 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 + */ +[LinkName("SDL_RemoveTimer")] public static extern bool RemoveTimer(TimerID id); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_timer_h_ */ \ No newline at end of file diff --git a/src/SDL_touch.bf b/src/SDL_touch.bf new file mode 100644 index 0000000..d9a5ba2 --- /dev/null +++ b/src/SDL_touch.bf @@ -0,0 +1,195 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias TouchID = Uint64; + +/** + * 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. + */ +public typealias FingerID = Uint64; + +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum TouchDeviceType : c_int +{ + Invalid = -1, + Direct, /**< touch screen with window-relative coordinates */ + IndirectAbsolute, /**< trackpad with absolute device coordinates */ + IndirectRelative, /**< trackpad with screen cursor-relative coordinates */ +} + +/** + * 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 + */ +[CRepr] public struct Finger +{ + public FingerID id; /**< the finger ID */ + public float x; /**< the x-axis location of the touch event, normalized (0...1) */ + public float y; /**< the y-axis location of the touch event, normalized (0...1) */ + public float pressure; /**< the quantity of pressure applied, normalized (0...1) */ +} + +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ +public const let 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. + */ +public const let 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. + */ +[LinkName("SDL_GetTouchDevices")] public static extern TouchID* GetTouchDevices(out c_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. + */ +[LinkName("SDL_GetTouchDeviceName")] public static extern c_char* GetTouchDeviceName(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. + */ +[LinkName("SDL_GetTouchDeviceType")] public static extern TouchDeviceType GetTouchDeviceType(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. + */ +[LinkName("SDL_GetTouchFingers")] public static extern Finger** GetTouchFingers(TouchID touchID, out c_int count); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_touch_h_ */ \ No newline at end of file diff --git a/src/SDL_tray.bf b/src/SDL_tray.bf new file mode 100644 index 0000000..c556fa3 --- /dev/null +++ b/src/SDL_tray.bf @@ -0,0 +1,556 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +[CRepr] public struct 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 + */ +public enum TrayEntryFlags : Uint32 +{ + Button = 0x00000001u, /**< Make the entry a simple button. Required. */ + Checkbox = 0x00000002u, /**< Make the entry a checkbox. Required. */ + Submenu = 0x00000004u, /**< Prepare the entry to have a submenu. Required */ + Disabled = 0x80000000u, /**< Make the entry disabled. Optional. */ + Checked = 0x40000000u, /**< Make the entry checked. This is valid only for checkboxes. Optional. */ +} /**< 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 + */ +public function void TrayCallback(void* userdata, 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 + */ +[LinkName("SDL_CreateTray")] public static extern Tray* CreateTray(Surface* icon, c_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 + */ +[LinkName("SDL_SetTrayIcon")] public static extern void SetTrayIcon(Tray* tray, 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 + */ +[LinkName("SDL_SetTrayTooltip")] public static extern void SetTrayTooltip(Tray* tray, c_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 + */ +[LinkName("SDL_CreateTrayMenu")] public static extern TrayMenu* CreateTrayMenu(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 + */ +[LinkName("SDL_CreateTraySubmenu")] public static extern TrayMenu* CreateTraySubmenu(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 + */ +[LinkName("SDL_GetTrayMenu")] public static extern TrayMenu* GetTrayMenu(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 + */ +[LinkName("SDL_GetTraySubmenu")] public static extern TrayMenu* GetTraySubmenu(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 + */ +[LinkName("SDL_GetTrayEntries")] public static extern TrayEntry** GetTrayEntries(TrayMenu* menu, c_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 + */ +[LinkName("SDL_RemoveTrayEntry")] public static extern void RemoveTrayEntry(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 + */ +[LinkName("SDL_InsertTrayEntryAt")] public static extern TrayEntry* InsertTrayEntryAt(TrayMenu* menu, c_int pos, c_char* label, 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 + */ +[LinkName("SDL_SetTrayEntryLabel")] public static extern void SetTrayEntryLabel(TrayEntry* entry, c_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 + */ +[LinkName("SDL_GetTrayEntryLabel")] public static extern c_char* GetTrayEntryLabel(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 + */ +[LinkName("SDL_SetTrayEntryChecked")] public static extern void SetTrayEntryChecked(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 + */ +[LinkName("SDL_GetTrayEntryChecked")] public static extern bool GetTrayEntryChecked(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 + */ +[LinkName("SDL_SetTrayEntryEnabled")] public static extern void SetTrayEntryEnabled(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 + */ +[LinkName("SDL_GetTrayEntryEnabled")] public static extern bool GetTrayEntryEnabled(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 + */ +[LinkName("SDL_SetTrayEntryCallback")] public static extern void SetTrayEntryCallback(TrayEntry* entry, 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. + */ +[LinkName("SDL_ClickTrayEntry")] public static extern void ClickTrayEntry(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 + */ +[LinkName("SDL_DestroyTray")] public static extern void DestroyTray(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 + */ +[LinkName("SDL_GetTrayEntryParent")] public static extern TrayMenu* GetTrayEntryParent(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 + */ +[LinkName("SDL_GetTrayMenuParentEntry")] public static extern TrayEntry* GetTrayMenuParentEntry(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 + */ +[LinkName("SDL_GetTrayMenuParentTray")] public static extern Tray* GetTrayMenuParentTray(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. + */ +[LinkName("SDL_UpdateTrays")] public static extern void UpdateTrays(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_tray_h_ */ \ No newline at end of file diff --git a/src/SDL_version.bf b/src/SDL_version.bf new file mode 100644 index 0000000..f351500 --- /dev/null +++ b/src/SDL_version.bf @@ -0,0 +1,195 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public const let 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. + */ +public const let MINOR_VERSION = 5; + +/** + * 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. + */ +public const let MICRO_VERSION = 0; + +/** + * 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. + */ +public static c_int VERSIONNUM(c_int major, c_int minor, c_int patch) => ((major)*1000000+(minor)*1000+(patch)); + + +/** + * This macro extracts the major version from a version number + * + * 1002003 becomes 1. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +public static c_int VERSIONNUM_MAJOR(c_int version) => ((version)/1000000); + +/** + * This macro extracts the minor version from a version number + * + * 1002003 becomes 2. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +public static c_int VERSIONNUM_MINOR(c_int version) => (((version)/1000)%1000); + +/** + * This macro extracts the micro version from a version number + * + * 1002003 becomes 3. + * + * \param version the version number. + * + * \since This macro is available since SDL 3.2.0. + */ +public static c_int VERSIONNUM_MICRO(c_int version) => ((version)%1000); + +/** + * This is the version number macro for the current SDL version. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion + */ +public const let VERSION + = VERSIONNUM(MAJOR_VERSION, MINOR_VERSION, MICRO_VERSION); + + +/** + * This macro will evaluate to true if compiled with SDL at least X.Y.Z. + * + * \since This macro is available since SDL 3.2.0. + */ +public static bool VERSION_ATLEAST(c_int X, c_int Y, c_int Z) => (VERSION>=VERSIONNUM(X,Y,Z)); + + +/** + * Get the version of SDL that is linked against your program. + * + * If you are linking to SDL dynamically, then it is possible that the current + * version will be different than the version you compiled against. This + * function returns the current version, while SDL_VERSION is the version you + * compiled with. + * + * This function may be called safely at any time, even before SDL_Init(). + * + * \returns the version of the linked library. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRevision + */ +[LinkName("SDL_GetVersion")] public static extern c_int GetVersion(); + +/** + * 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. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetVersion + */ +[LinkName("SDL_GetRevision")] public static extern c_char* GetRevision(); +} + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_version_h_ */ \ No newline at end of file diff --git a/src/SDL_video.bf b/src/SDL_video.bf new file mode 100644 index 0000000..8ac5569 --- /dev/null +++ b/src/SDL_video.bf @@ -0,0 +1,3448 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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(). + */ + + + + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/** + * 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. + */ +public typealias DisplayID = Uint32; + +/** + * 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. + */ +public typealias WindowID = Uint32; + +/* 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. + */ +public const let PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER = "SDL.video.wayland.wl_display"; + +/** + * System theme. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum SystemTheme : c_int +{ + Unknown, /**< Unknown system theme */ + Light, /**< Light colored system theme */ + Dark, /**< Dark colored system theme */ +} + +/** + * 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 + */ +[CRepr] public struct 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 + */ +[CRepr] public struct DisplayMode +{ + public DisplayID displayID; /**< the display this mode is associated with */ + public PixelFormat format; /**< pixel format */ + public c_int w; /**< width */ + public c_int h; /**< height */ + public float pixel_density; /**< scale converting size to pixels (e.g. a 1920x1080 mode with 2.0 scale would have 3840x2160 pixels) */ + public float refresh_rate; /**< refresh rate (or 0.0f for unspecified) */ + public c_int refresh_rate_numerator; /**< precise refresh rate numerator (or 0 for unspecified) */ + public c_int refresh_rate_denominator; /**< precise refresh rate denominator */ + + public DisplayModeData* @internal; /**< Private */ + +} + +/** + * Display orientation values; the way a display is rotated. + * + * \since This enum is available since SDL 3.2.0. + */ +[AllowDuplicates] public enum DisplayOrientation : c_int +{ + OrientationUnknown, /**< The display orientation can't be determined */ + OrientationLandscape, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ + OrientationLandscapeFlipped, /**< The display is in landscape mode, with the left side up, relative to portrait mode */ + OrientationPortrait, /**< The display is in portrait mode */ + OrientationPortraitFlipped, /**< The display is in portrait mode, upside down */ +} + +/** + * The struct used as an opaque handle to a window. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateWindow + */ +[CRepr] public struct 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 + */ +public enum WindowFlags : Uint64 +{ + Fullscreen = UINT64_C(0x0000000000000001), /**< window is in fullscreen mode */ + Opengl = UINT64_C(0x0000000000000002), /**< window usable with OpenGL context */ + Occluded = UINT64_C(0x0000000000000004), /**< window is occluded */ + Hidden = 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 */ + Borderless = UINT64_C(0x0000000000000010), /**< no window decoration */ + Resizable = UINT64_C(0x0000000000000020), /**< window can be resized */ + Minimized = UINT64_C(0x0000000000000040), /**< window is minimized */ + Maximized = UINT64_C(0x0000000000000080), /**< window is maximized */ + MouseGrabbed = UINT64_C(0x0000000000000100), /**< window has grabbed mouse input */ + InputFocus = UINT64_C(0x0000000000000200), /**< window has input focus */ + MouseFocus = UINT64_C(0x0000000000000400), /**< window has mouse focus */ + External = UINT64_C(0x0000000000000800), /**< window not created by SDL */ + Modal = UINT64_C(0x0000000000001000), /**< window is modal */ + HighPixelDensity = UINT64_C(0x0000000000002000), /**< window uses high pixel density back buffer if possible */ + MouseCapture = UINT64_C(0x0000000000004000), /**< window has mouse captured (unrelated to MOUSE_GRABBED) */ + MouseRelativeMode = UINT64_C(0x0000000000008000), /**< window has relative mode enabled */ + AlwaysOnTop = UINT64_C(0x0000000000010000), /**< window should always be above others */ + Utility = UINT64_C(0x0000000000020000), /**< window should be treated as a utility window, not showing in the task bar and window list */ + Tooltip = UINT64_C(0x0000000000040000), /**< window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window */ + PopupMenu = UINT64_C(0x0000000000080000), /**< window should be treated as a popup menu, requires a parent window */ + KeyboardGrabbed = UINT64_C(0x0000000000100000), /**< window has grabbed keyboard input */ + FillDocument = UINT64_C(0x0000000000200000), /**< window is in fill-document mode (Emscripten only), since SDL 3.4.0 */ + Vulkan = UINT64_C(0x0000000010000000), /**< window usable for Vulkan surface */ + Metal = UINT64_C(0x0000000020000000), /**< window usable for Metal view */ + Transparent = UINT64_C(0x0000000040000000), /**< window with transparent buffer */ + NotFocusable = UINT64_C(0x0000000080000000), /**< window should not be focusable */ + SurfaceVsyncDisabled = 0, + SurfaceVsyncAdaptive = (-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 + */ +}[AllowDuplicates] public enum FlashOperation : c_int +{ + Cancel, /**< Cancel any window flash state */ + Briefly, /**< Flash the window briefly to get attention */ + UntilFocused, /**< Flash the window until it gets focus */ +} + +/** + * Window progress state + * + * \since This enum is available since SDL 3.2.8. + */ +[AllowDuplicates] public enum ProgressState : c_int +{ + Invalid = -1, /**< An invalid progress state indicating an error; check SDL_GetError() */ + None, /**< No progress bar is shown */ + Indeterminate, /**< The progress bar is shown in a indeterminate state */ + Normal, /**< The progress bar is shown in a normal state */ + Paused, /**< The progress bar is shown in a paused state */ + Error, /**< The progress bar is shown in a state indicating the application had an error */ +} + +/** + * 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 + */ +[CRepr] public struct GLContextState; public typealias GLContext = GLContextState*; + +/** + * Opaque type for an EGL display. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias EGLDisplay = void*; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias EGLConfig = void*; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias EGLSurface = void*; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias EGLAttrib = c_intptr; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ +public typealias EGLint = c_int; + +/** + * 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 + */ +public function EGLAttrib* 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 + */ +public function EGLint* EGLIntArrayCallback(void* userdata, EGLDisplay display, 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. + */ +[AllowDuplicates] public enum GLAttr : c_int +{ + RedSize, /**< the minimum number of bits for the red channel of the color buffer; defaults to 8. */ + GreenSize, /**< the minimum number of bits for the green channel of the color buffer; defaults to 8. */ + BlueSize, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 8. */ + lphaSize, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 8. */ + BufferSize, /**< the minimum number of bits for frame buffer size; defaults to 0. */ + Doublebuffer, /**< whether the output is single or double buffered; defaults to double buffering on. */ + DepthSize, /**< the minimum number of bits in the depth buffer; defaults to 16. */ + StencilSize, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ + ccumRedSize, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ + ccumGreenSize, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ + ccumBlueSize, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ + ccumAlphaSize, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ + Stereo, /**< whether the output is stereo 3D; defaults to off. */ + Multisamplebuffers, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ + Multisamplesamples, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ + cceleratedVisual, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ + RetainedBacking, /**< not used (deprecated). */ + ContextMajorVersion, /**< OpenGL context major version. */ + ContextMinorVersion, /**< OpenGL context minor version. */ + ContextFlags, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + ContextProfileMask, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ + ShareWithCurrentContext, /**< OpenGL context sharing; defaults to 0. */ + FramebufferSrgbCapable, /**< requests sRGB-capable visual if 1. Defaults to -1 ("don't care"). This is a request; GL drivers might not comply! */ + ContextReleaseBehavior, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ + ContextResetNotification, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ + ContextNoError, + Floatbuffers, + EglPlatform, +} + +/** + * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum GLProfile : Uint32 +{ + Core = 0x0001, /**< OpenGL Core Profile context */ + Compatibility = 0x0002, /**< OpenGL Compatibility Profile context */ + Es = 0x0004, /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ +} /**< 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. + */ +public enum GLContextFlag : Uint32 +{ + Debug = 0x0001, + ForwardCompatible = 0x0002, + RobustAccess = 0x0004, + ResetIsolation = 0x0008, + + +/** + * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR + * attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +} + + +/** + * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR + * attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum GLContextReleaseFlag : Uint32 +{ + BehaviorNone = 0x0000, + BehaviorFlush = 0x0001, + + +/** + * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +} + + +/** + * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. + * + * \since This datatype is available since SDL 3.2.0. + */ +public enum GLContextResetNotification : Uint32 +{ + NoNotification = 0x0000, + LoseContext = 0x0001, + + +/* Function prototypes */ +} + + +/* 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 + */ +[LinkName("SDL_GetNumVideoDrivers")] public static extern c_int GetNumVideoDrivers(); + +/** + * 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 + */ +[LinkName("SDL_GetVideoDriver")] public static extern c_char* GetVideoDriver(c_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 + */ +[LinkName("SDL_GetCurrentVideoDriver")] public static extern c_char* GetCurrentVideoDriver(); + +/** + * 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. + */ +[LinkName("SDL_GetSystemTheme")] public static extern SystemTheme GetSystemTheme(); + +/** + * 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. + */ +[LinkName("SDL_GetDisplays")] public static extern DisplayID* GetDisplays(out c_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 + */ +[LinkName("SDL_GetPrimaryDisplay")] public static extern DisplayID GetPrimaryDisplay(); + +/** + * 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. + */ +[LinkName("SDL_GetDisplayProperties")] public static extern PropertiesID GetDisplayProperties(DisplayID displayID); + +public const let PROP_DISPLAY_HDR_ENABLED_BOOLEAN = "SDL.display.HDR_enabled"; +public const let PROP_DISPLAY_KMSDRM_PANEL_ORIENTATION_NUMBER = "SDL.display.KMSDRM.panel_orientation"; +public const let PROP_DISPLAY_WAYLAND_WL_OUTPUT_POINTER = "SDL.display.wayland.wl_output"; +public const let 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 + */ +[LinkName("SDL_GetDisplayName")] public static extern c_char* GetDisplayName(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 + */ +[LinkName("SDL_GetDisplayBounds")] public static extern bool GetDisplayBounds(DisplayID displayID, 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 + */ +[LinkName("SDL_GetDisplayUsableBounds")] public static extern bool GetDisplayUsableBounds(DisplayID displayID, 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 + */ +[LinkName("SDL_GetNaturalDisplayOrientation")] public static extern DisplayOrientation GetNaturalDisplayOrientation(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 + */ +[LinkName("SDL_GetCurrentDisplayOrientation")] public static extern DisplayOrientation GetCurrentDisplayOrientation(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 + */ +[LinkName("SDL_GetDisplayContentScale")] public static extern float GetDisplayContentScale(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 + */ +[LinkName("SDL_GetFullscreenDisplayModes")] public static extern DisplayMode** GetFullscreenDisplayModes(DisplayID displayID, out c_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 + */ +[LinkName("SDL_GetClosestFullscreenDisplayMode")] public static extern bool GetClosestFullscreenDisplayMode(DisplayID displayID, c_int w, c_int h, float refresh_rate, bool include_high_density_modes, out 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 + */ +[LinkName("SDL_GetDesktopDisplayMode")] public static extern DisplayMode* GetDesktopDisplayMode(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 + */ +[LinkName("SDL_GetCurrentDisplayMode")] public static extern DisplayMode* GetCurrentDisplayMode(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 + */ +[LinkName("SDL_GetDisplayForPoint")] public static extern DisplayID GetDisplayForPoint(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 + */ +[LinkName("SDL_GetDisplayForRect")] public static extern DisplayID GetDisplayForRect(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 + */ +[LinkName("SDL_GetDisplayForWindow")] public static extern DisplayID GetDisplayForWindow(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 + */ +[LinkName("SDL_GetWindowPixelDensity")] public static extern float GetWindowPixelDensity(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. + */ +[LinkName("SDL_GetWindowDisplayScale")] public static extern float GetWindowDisplayScale(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 + */ +[LinkName("SDL_SetWindowFullscreenMode")] public static extern bool SetWindowFullscreenMode(Window* window, 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 + */ +[LinkName("SDL_GetWindowFullscreenMode")] public static extern DisplayMode* GetWindowFullscreenMode(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. + */ +[LinkName("SDL_GetWindowICCProfile")] public static extern void* GetWindowICCProfile(Window* window, c_size* 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. + */ +[LinkName("SDL_GetWindowPixelFormat")] public static extern PixelFormat GetWindowPixelFormat(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. + */ +[LinkName("SDL_GetWindows")] public static extern Window** GetWindows(out c_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 + */ +[LinkName("SDL_CreateWindow")] public static extern Window* CreateWindow(c_char* title, c_int w, c_int h, 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 + */ +[LinkName("SDL_CreatePopupWindow")] public static extern Window* CreatePopupWindow(Window* parent, c_int offset_x, c_int offset_y, c_int w, c_int h, 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 + */ +[LinkName("SDL_CreateWindowWithProperties")] public static extern Window* CreateWindowWithProperties(PropertiesID props); + +public const let PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN = "SDL.window.create.always_on_top"; +public const let PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN = "SDL.window.create.borderless"; +public const let PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN = "SDL.window.create.constrain_popup"; +public const let PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN = "SDL.window.create.focusable"; +public const let PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN = "SDL.window.create.external_graphics_context"; +public const let PROP_WINDOW_CREATE_FLAGS_NUMBER = "SDL.window.create.flags"; +public const let PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN = "SDL.window.create.fullscreen"; +public const let PROP_WINDOW_CREATE_HEIGHT_NUMBER = "SDL.window.create.height"; +public const let PROP_WINDOW_CREATE_HIDDEN_BOOLEAN = "SDL.window.create.hidden"; +public const let PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN = "SDL.window.create.high_pixel_density"; +public const let PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN = "SDL.window.create.maximized"; +public const let PROP_WINDOW_CREATE_MENU_BOOLEAN = "SDL.window.create.menu"; +public const let PROP_WINDOW_CREATE_METAL_BOOLEAN = "SDL.window.create.metal"; +public const let PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN = "SDL.window.create.minimized"; +public const let PROP_WINDOW_CREATE_MODAL_BOOLEAN = "SDL.window.create.modal"; +public const let PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN = "SDL.window.create.mouse_grabbed"; +public const let PROP_WINDOW_CREATE_OPENGL_BOOLEAN = "SDL.window.create.opengl"; +public const let PROP_WINDOW_CREATE_PARENT_POINTER = "SDL.window.create.parent"; +public const let PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN = "SDL.window.create.resizable"; +public const let PROP_WINDOW_CREATE_TITLE_STRING = "SDL.window.create.title"; +public const let PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN = "SDL.window.create.transparent"; +public const let PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN = "SDL.window.create.tooltip"; +public const let PROP_WINDOW_CREATE_UTILITY_BOOLEAN = "SDL.window.create.utility"; +public const let PROP_WINDOW_CREATE_VULKAN_BOOLEAN = "SDL.window.create.vulkan"; +public const let PROP_WINDOW_CREATE_WIDTH_NUMBER = "SDL.window.create.width"; +public const let PROP_WINDOW_CREATE_X_NUMBER = "SDL.window.create.x"; +public const let PROP_WINDOW_CREATE_Y_NUMBER = "SDL.window.create.y"; +public const let PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER = "SDL.window.create.cocoa.window"; +public const let PROP_WINDOW_CREATE_COCOA_VIEW_POINTER = "SDL.window.create.cocoa.view"; +public const let PROP_WINDOW_CREATE_WINDOWSCENE_POINTER = "SDL.window.create.uikit.windowscene"; +public const let PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN = "SDL.window.create.wayland.surface_role_custom"; +public const let PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN = "SDL.window.create.wayland.create_egl_window"; +public const let PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER = "SDL.window.create.wayland.wl_surface"; +public const let PROP_WINDOW_CREATE_WIN32_HWND_POINTER = "SDL.window.create.win32.hwnd"; +public const let PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER = "SDL.window.create.win32.pixel_format_hwnd"; +public const let PROP_WINDOW_CREATE_X11_WINDOW_NUMBER = "SDL.window.create.x11.window"; +public const let PROP_WINDOW_CREATE_EMSCRIPTEN_CANVAS_ID_STRING = "SDL.window.create.emscripten.canvas_id"; +public const let 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 + */ +[LinkName("SDL_GetWindowID")] public static extern WindowID GetWindowID(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 + */ +[LinkName("SDL_GetWindowFromID")] public static extern Window* GetWindowFromID(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 + */ +[LinkName("SDL_GetWindowParent")] public static extern Window* GetWindowParent(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 QNX: + * + * - `SDL_PROP_WINDOW_QNX_WINDOW_POINTER`: the screen_window_t associated with + * the window. + * - `SDL_PROP_WINDOW_QNX_SURFACE_POINTER`: the EGLSurface associated with the + * 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. + */ +[LinkName("SDL_GetWindowProperties")] public static extern PropertiesID GetWindowProperties(Window* window); + +public const let PROP_WINDOW_SHAPE_POINTER = "SDL.window.shape"; +public const let PROP_WINDOW_HDR_ENABLED_BOOLEAN = "SDL.window.HDR_enabled"; +public const let PROP_WINDOW_SDR_WHITE_LEVEL_FLOAT = "SDL.window.SDR_white_level"; +public const let PROP_WINDOW_HDR_HEADROOM_FLOAT = "SDL.window.HDR_headroom"; +public const let PROP_WINDOW_ANDROID_WINDOW_POINTER = "SDL.window.android.window"; +public const let PROP_WINDOW_ANDROID_SURFACE_POINTER = "SDL.window.android.surface"; +public const let PROP_WINDOW_UIKIT_WINDOW_POINTER = "SDL.window.uikit.window"; +public const let PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER = "SDL.window.uikit.metal_view_tag"; +public const let PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER = "SDL.window.uikit.opengl.framebuffer"; +public const let PROP_WINDOW_UIKIT_OPENGL_RENDERBUFFER_NUMBER = "SDL.window.uikit.opengl.renderbuffer"; +public const let PROP_WINDOW_UIKIT_OPENGL_RESOLVE_FRAMEBUFFER_NUMBER = "SDL.window.uikit.opengl.resolve_framebuffer"; +public const let PROP_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER = "SDL.window.kmsdrm.dev_index"; +public const let PROP_WINDOW_KMSDRM_DRM_FD_NUMBER = "SDL.window.kmsdrm.drm_fd"; +public const let PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER = "SDL.window.kmsdrm.gbm_dev"; +public const let PROP_WINDOW_COCOA_WINDOW_POINTER = "SDL.window.cocoa.window"; +public const let PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER = "SDL.window.cocoa.metal_view_tag"; +public const let PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER = "SDL.window.openvr.overlay_id"; +public const let PROP_WINDOW_QNX_WINDOW_POINTER = "SDL.window.qnx.window"; +public const let PROP_WINDOW_QNX_SURFACE_POINTER = "SDL.window.qnx.surface"; +public const let PROP_WINDOW_VIVANTE_DISPLAY_POINTER = "SDL.window.vivante.display"; +public const let PROP_WINDOW_VIVANTE_WINDOW_POINTER = "SDL.window.vivante.window"; +public const let PROP_WINDOW_VIVANTE_SURFACE_POINTER = "SDL.window.vivante.surface"; +public const let PROP_WINDOW_WIN32_HWND_POINTER = "SDL.window.win32.hwnd"; +public const let PROP_WINDOW_WIN32_HDC_POINTER = "SDL.window.win32.hdc"; +public const let PROP_WINDOW_WIN32_INSTANCE_POINTER = "SDL.window.win32.instance"; +public const let PROP_WINDOW_WAYLAND_DISPLAY_POINTER = "SDL.window.wayland.display"; +public const let PROP_WINDOW_WAYLAND_SURFACE_POINTER = "SDL.window.wayland.surface"; +public const let PROP_WINDOW_WAYLAND_VIEWPORT_POINTER = "SDL.window.wayland.viewport"; +public const let PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER = "SDL.window.wayland.egl_window"; +public const let PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER = "SDL.window.wayland.xdg_surface"; +public const let PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER = "SDL.window.wayland.xdg_toplevel"; +public const let PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_EXPORT_HANDLE_STRING = "SDL.window.wayland.xdg_toplevel_export_handle"; +public const let PROP_WINDOW_WAYLAND_XDG_POPUP_POINTER = "SDL.window.wayland.xdg_popup"; +public const let PROP_WINDOW_WAYLAND_XDG_POSITIONER_POINTER = "SDL.window.wayland.xdg_positioner"; +public const let PROP_WINDOW_X11_DISPLAY_POINTER = "SDL.window.x11.display"; +public const let PROP_WINDOW_X11_SCREEN_NUMBER = "SDL.window.x11.screen"; +public const let PROP_WINDOW_X11_WINDOW_NUMBER = "SDL.window.x11.window"; +public const let PROP_WINDOW_EMSCRIPTEN_CANVAS_ID_STRING = "SDL.window.emscripten.canvas_id"; +public const let 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 + */ +[LinkName("SDL_GetWindowFlags")] public static extern WindowFlags GetWindowFlags(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 + */ +[LinkName("SDL_SetWindowTitle")] public static extern bool SetWindowTitle(Window* window, c_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 + */ +[LinkName("SDL_GetWindowTitle")] public static extern c_char* GetWindowTitle(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 + */ +[LinkName("SDL_SetWindowIcon")] public static extern bool SetWindowIcon(Window* window, 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 + */ +[LinkName("SDL_SetWindowPosition")] public static extern bool SetWindowPosition(Window* window, c_int x, c_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 + */ +[LinkName("SDL_GetWindowPosition")] public static extern bool GetWindowPosition(Window* window, out c_int x, out c_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 + */ +[LinkName("SDL_SetWindowSize")] public static extern bool SetWindowSize(Window* window, c_int w, c_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 + */ +[LinkName("SDL_GetWindowSize")] public static extern bool GetWindowSize(Window* window, out c_int w, out c_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. + */ +[LinkName("SDL_GetWindowSafeArea")] public static extern bool GetWindowSafeArea(Window* window, out 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 + */ +[LinkName("SDL_SetWindowAspectRatio")] public static extern bool SetWindowAspectRatio(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 + */ +[LinkName("SDL_GetWindowAspectRatio")] public static extern bool GetWindowAspectRatio(Window* window, out float min_aspect, out 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 + */ +[LinkName("SDL_GetWindowBordersSize")] public static extern bool GetWindowBordersSize(Window* window, c_int* top, c_int* left, c_int* bottom, c_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 + */ +[LinkName("SDL_GetWindowSizeInPixels")] public static extern bool GetWindowSizeInPixels(Window* window, c_int* w, c_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 + */ +[LinkName("SDL_SetWindowMinimumSize")] public static extern bool SetWindowMinimumSize(Window* window, c_int min_w, c_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 + */ +[LinkName("SDL_GetWindowMinimumSize")] public static extern bool GetWindowMinimumSize(Window* window, out c_int w, out c_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 + */ +[LinkName("SDL_SetWindowMaximumSize")] public static extern bool SetWindowMaximumSize(Window* window, c_int max_w, c_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 + */ +[LinkName("SDL_GetWindowMaximumSize")] public static extern bool GetWindowMaximumSize(Window* window, out c_int w, out c_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 + */ +[LinkName("SDL_SetWindowBordered")] public static extern bool SetWindowBordered(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 + */ +[LinkName("SDL_SetWindowResizable")] public static extern bool SetWindowResizable(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 + */ +[LinkName("SDL_SetWindowAlwaysOnTop")] public static extern bool SetWindowAlwaysOnTop(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 + */ +[LinkName("SDL_SetWindowFillDocument")] public static extern bool SetWindowFillDocument(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 + */ +[LinkName("SDL_ShowWindow")] public static extern bool ShowWindow(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 + */ +[LinkName("SDL_HideWindow")] public static extern bool HideWindow(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. + */ +[LinkName("SDL_RaiseWindow")] public static extern bool RaiseWindow(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 + */ +[LinkName("SDL_MaximizeWindow")] public static extern bool MaximizeWindow(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 + */ +[LinkName("SDL_MinimizeWindow")] public static extern bool MinimizeWindow(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 + */ +[LinkName("SDL_RestoreWindow")] public static extern bool RestoreWindow(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 + */ +[LinkName("SDL_SetWindowFullscreen")] public static extern bool SetWindowFullscreen(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 + */ +[LinkName("SDL_SyncWindow")] public static extern bool SyncWindow(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 + */ +[LinkName("SDL_WindowHasSurface")] public static extern bool WindowHasSurface(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 + */ +[LinkName("SDL_GetWindowSurface")] public static extern Surface* GetWindowSurface(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 + */ +[LinkName("SDL_SetWindowSurfaceVSync")] public static extern bool SetWindowSurfaceVSync(Window* window, c_int vsync); + + + + +/** + * 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 + */ +[LinkName("SDL_GetWindowSurfaceVSync")] public static extern bool GetWindowSurfaceVSync(Window* window, c_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 + */ +[LinkName("SDL_UpdateWindowSurface")] public static extern bool UpdateWindowSurface(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 + */ +[LinkName("SDL_UpdateWindowSurfaceRects")] public static extern bool UpdateWindowSurfaceRects(Window* window, Rect* rects, c_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 + */ +[LinkName("SDL_DestroyWindowSurface")] public static extern bool DestroyWindowSurface(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 + */ +[LinkName("SDL_SetWindowKeyboardGrab")] public static extern bool SetWindowKeyboardGrab(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 + */ +[LinkName("SDL_SetWindowMouseGrab")] public static extern bool SetWindowMouseGrab(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 + */ +[LinkName("SDL_GetWindowKeyboardGrab")] public static extern bool GetWindowKeyboardGrab(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 + */ +[LinkName("SDL_GetWindowMouseGrab")] public static extern bool GetWindowMouseGrab(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 + */ +[LinkName("SDL_GetGrabbedWindow")] public static extern Window* GetGrabbedWindow(); + +/** + * 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 + */ +[LinkName("SDL_SetWindowMouseRect")] public static extern bool SetWindowMouseRect(Window* window, 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 + */ +[LinkName("SDL_GetWindowMouseRect")] public static extern Rect* GetWindowMouseRect(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 + */ +[LinkName("SDL_SetWindowOpacity")] public static extern bool SetWindowOpacity(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 + */ +[LinkName("SDL_GetWindowOpacity")] public static extern float GetWindowOpacity(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 + */ +[LinkName("SDL_SetWindowParent")] public static extern bool SetWindowParent(Window* window, 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 + */ +[LinkName("SDL_SetWindowModal")] public static extern bool SetWindowModal(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. + */ +[LinkName("SDL_SetWindowFocusable")] public static extern bool SetWindowFocusable(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. + */ +[LinkName("SDL_ShowWindowSystemMenu")] public static extern bool ShowWindowSystemMenu(Window* window, c_int x, c_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 + */ +[AllowDuplicates] public enum HitTestResult : c_int +{ + Normal, /**< Region is normal. No special properties. */ + Draggable, /**< Region can drag entire window. */ + izeTopleft, /**< Region is the resizable top-left corner border. */ + izeTop, /**< Region is the resizable top border. */ + izeTopright, /**< Region is the resizable top-right corner border. */ + izeRight, /**< Region is the resizable right border. */ + izeBottomright, /**< Region is the resizable bottom-right corner border. */ + izeBottom, /**< Region is the resizable bottom border. */ + izeBottomleft, /**< Region is the resizable bottom-left corner border. */ + izeLeft, /**< Region is the resizable left border. */ +} + +/** + * 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 + */ +public function HitTestResult HitTest(Window* win, 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. + */ +[LinkName("SDL_SetWindowHitTest")] public static extern bool SetWindowHitTest(Window* window, 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. + */ +[LinkName("SDL_SetWindowShape")] public static extern bool SetWindowShape(Window* window, 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. + */ +[LinkName("SDL_FlashWindow")] public static extern bool FlashWindow(Window* window, 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. + */ +[LinkName("SDL_SetWindowProgressState")] public static extern bool SetWindowProgressState(Window* window, 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. + */ +[LinkName("SDL_GetWindowProgressState")] public static extern ProgressState GetWindowProgressState(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. + */ +[LinkName("SDL_SetWindowProgressValue")] public static extern bool SetWindowProgressValue(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. + */ +[LinkName("SDL_GetWindowProgressValue")] public static extern float GetWindowProgressValue(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 + */ +[LinkName("SDL_DestroyWindow")] public static extern void DestroyWindow(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 + */ +[LinkName("SDL_ScreenSaverEnabled")] public static extern bool ScreenSaverEnabled(); + +/** + * 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 + */ +[LinkName("SDL_EnableScreenSaver")] public static extern bool EnableScreenSaver(); + +/** + * 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 + */ +[LinkName("SDL_DisableScreenSaver")] public static extern bool DisableScreenSaver(); + + +/** + * \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 + */ +[LinkName("SDL_GL_LoadLibrary")] public static extern bool GL_LoadLibrary(c_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 + */ +[LinkName("SDL_GL_GetProcAddress")] public static extern FunctionPointer GL_GetProcAddress(c_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 + */ +[LinkName("SDL_EGL_GetProcAddress")] public static extern FunctionPointer EGL_GetProcAddress(c_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 + */ +[LinkName("SDL_GL_UnloadLibrary")] public static extern void GL_UnloadLibrary(); + +/** + * 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. + */ +[LinkName("SDL_GL_ExtensionSupported")] public static extern bool GL_ExtensionSupported(c_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 + */ +[LinkName("SDL_GL_ResetAttributes")] public static extern void GL_ResetAttributes(); + +/** + * 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 + */ +[LinkName("SDL_GL_SetAttribute")] public static extern bool GL_SetAttribute(GLAttr attr, c_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 + */ +[LinkName("SDL_GL_GetAttribute")] public static extern bool GL_GetAttribute(GLAttr attr, out c_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 + */ +[LinkName("SDL_GL_CreateContext")] public static extern GLContext GL_CreateContext(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 + */ +[LinkName("SDL_GL_MakeCurrent")] public static extern bool GL_MakeCurrent(Window* window, 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. + */ +[LinkName("SDL_GL_GetCurrentWindow")] public static extern Window* GL_GetCurrentWindow(); + +/** + * 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 + */ +[LinkName("SDL_GL_GetCurrentContext")] public static extern GLContext GL_GetCurrentContext(); + +/** + * 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. + */ +[LinkName("SDL_EGL_GetCurrentDisplay")] public static extern EGLDisplay EGL_GetCurrentDisplay(); + +/** + * 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. + */ +[LinkName("SDL_EGL_GetCurrentConfig")] public static extern EGLConfig EGL_GetCurrentConfig(); + +/** + * 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. + */ +[LinkName("SDL_EGL_GetWindowSurface")] public static extern EGLSurface EGL_GetWindowSurface(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. + */ +[LinkName("SDL_EGL_SetAttributeCallbacks")] public static extern void EGL_SetAttributeCallbacks(EGLAttribArrayCallback platformAttribCallback, EGLIntArrayCallback surfaceAttribCallback, 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 + */ +[LinkName("SDL_GL_SetSwapInterval")] public static extern bool GL_SetSwapInterval(c_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 + */ +[LinkName("SDL_GL_GetSwapInterval")] public static extern bool GL_GetSwapInterval(c_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. + */ +[LinkName("SDL_GL_SwapWindow")] public static extern bool GL_SwapWindow(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 + */ +[LinkName("SDL_GL_DestroyContext")] public static extern bool GL_DestroyContext(GLContext context); +} + +/* @} */ /* OpenGL support functions */ + + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_video_h_ */ \ No newline at end of file diff --git a/src/SDL_vulkan.bf b/src/SDL_vulkan.bf new file mode 100644 index 0000000..d180c3a --- /dev/null +++ b/src/SDL_vulkan.bf @@ -0,0 +1,291 @@ +// This file was generated by Cpp2Beef + +using System; +using System.Interop; +using static SDL3.SDL; + +namespace SDL3; + +extension SDL +{ +/* + 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. + */ + + + + + + + + + +/* Set up for C function definitions, even when using C++ */ + + + + +/* Avoid including vulkan_core.h, don't define VkInstance if it's already included */ + + + + + + + + + + + + +[CRepr] public struct VkInstance_T;public typealias VkInstance = VkInstance_T*; +[CRepr] public struct VkPhysicalDevice_T;public typealias VkPhysicalDevice = VkPhysicalDevice_T*; +[CRepr] public struct VkSurfaceKHR_T;public typealias VkSurfaceKHR = VkSurfaceKHR_T*; +[CRepr] public struct VkAllocationCallbacks; + +/* Make sure to undef to avoid issues in case of later vulkan include */ + + + +/* !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 + */ +[LinkName("SDL_Vulkan_LoadLibrary")] public static extern bool Vulkan_LoadLibrary(c_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. + */ +[LinkName("SDL_Vulkan_GetVkGetInstanceProcAddr")] public static extern FunctionPointer Vulkan_GetVkGetInstanceProcAddr(); + +/** + * 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 + */ +[LinkName("SDL_Vulkan_UnloadLibrary")] public static extern void Vulkan_UnloadLibrary(); + +/** + * 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 + */ +[LinkName("SDL_Vulkan_GetInstanceExtensions")] public static extern c_char** Vulkan_GetInstanceExtensions(out 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 + */ +[LinkName("SDL_Vulkan_CreateSurface")] public static extern bool Vulkan_CreateSurface(Window* window, VkInstance instance, 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 + */ +[LinkName("SDL_Vulkan_DestroySurface")] public static extern void Vulkan_DestroySurface(VkInstance instance, VkSurfaceKHR surface, 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 + */ +[LinkName("SDL_Vulkan_GetPresentationSupport")] public static extern bool Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); +} + +/* @} */ /* Vulkan support functions */ + +/* Ends C function definitions when using C++ */ + + + + + +/* SDL_vulkan_h_ */ \ No newline at end of file