From 56e6e53d0cb273d61597eed90529f08fa5c5b728 Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Mon, 7 Oct 2024 21:53:20 +0300 Subject: [PATCH] Update SDL to 3.1.3 preview --- Source/Engine/Platform/SDL/SDLInput.cpp | 40 +- .../Engine/Platform/SDL/SDLPlatform.Linux.cpp | 24 +- .../Platform/SDL/SDLPlatform.Windows.cpp | 6 +- Source/Engine/Platform/SDL/SDLPlatform.cpp | 16 +- Source/Engine/Platform/SDL/SDLPlatform.h | 4 +- Source/Engine/Platform/SDL/SDLWindow.cpp | 30 +- Source/ThirdParty/SDL/SDL3/SDL.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_assert.h | 18 +- Source/ThirdParty/SDL/SDL3/SDL_atomic.h | 159 +- Source/ThirdParty/SDL/SDL3/SDL_audio.h | 250 +- Source/ThirdParty/SDL/SDL3/SDL_begin_code.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_bits.h | 11 +- Source/ThirdParty/SDL/SDL3/SDL_camera.h | 26 +- Source/ThirdParty/SDL/SDL3/SDL_clipboard.h | 54 +- Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h | 62 +- Source/ThirdParty/SDL/SDL3/SDL_dialog.h | 29 +- Source/ThirdParty/SDL/SDL3/SDL_error.h | 36 +- Source/ThirdParty/SDL/SDL3/SDL_events.h | 282 +- Source/ThirdParty/SDL/SDL3/SDL_filesystem.h | 230 +- Source/ThirdParty/SDL/SDL3/SDL_gamepad.h | 134 +- Source/ThirdParty/SDL/SDL3/SDL_gpu.h | 3712 +++++++++++++++++ Source/ThirdParty/SDL/SDL3/SDL_guid.h | 1 - Source/ThirdParty/SDL/SDL3/SDL_haptic.h | 133 +- Source/ThirdParty/SDL/SDL3/SDL_hidapi.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_hints.h | 474 +-- Source/ThirdParty/SDL/SDL3/SDL_init.h | 93 +- Source/ThirdParty/SDL/SDL3/SDL_iostream.h | 321 +- Source/ThirdParty/SDL/SDL3/SDL_joystick.h | 167 +- Source/ThirdParty/SDL/SDL3/SDL_keyboard.h | 88 +- Source/ThirdParty/SDL/SDL3/SDL_keycode.h | 2 +- Source/ThirdParty/SDL/SDL3/SDL_loadso.h | 34 +- Source/ThirdParty/SDL/SDL3/SDL_log.h | 94 +- Source/ThirdParty/SDL/SDL3/SDL_main.h | 96 +- Source/ThirdParty/SDL/SDL3/SDL_main_impl.h | 68 +- Source/ThirdParty/SDL/SDL3/SDL_messagebox.h | 16 +- Source/ThirdParty/SDL/SDL3/SDL_misc.h | 6 +- Source/ThirdParty/SDL/SDL3/SDL_mouse.h | 112 +- Source/ThirdParty/SDL/SDL3/SDL_mutex.h | 259 +- Source/ThirdParty/SDL/SDL3/SDL_oldnames.h | 56 +- Source/ThirdParty/SDL/SDL3/SDL_opengl_glext.h | 40 +- Source/ThirdParty/SDL/SDL3/SDL_pen.h | 273 +- Source/ThirdParty/SDL/SDL3/SDL_pixels.h | 119 +- .../SDL/SDL3/SDL_platform_defines.h | 379 +- Source/ThirdParty/SDL/SDL3/SDL_process.h | 417 ++ Source/ThirdParty/SDL/SDL3/SDL_properties.h | 66 +- Source/ThirdParty/SDL/SDL3/SDL_rect.h | 120 +- Source/ThirdParty/SDL/SDL3/SDL_render.h | 741 ++-- Source/ThirdParty/SDL/SDL3/SDL_revision.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_scancode.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_sensor.h | 22 +- Source/ThirdParty/SDL/SDL3/SDL_stdinc.h | 1515 ++++++- Source/ThirdParty/SDL/SDL3/SDL_storage.h | 124 +- Source/ThirdParty/SDL/SDL3/SDL_surface.h | 290 +- Source/ThirdParty/SDL/SDL3/SDL_system.h | 211 +- Source/ThirdParty/SDL/SDL3/SDL_test_assert.h | 15 +- Source/ThirdParty/SDL/SDL3/SDL_test_common.h | 67 +- Source/ThirdParty/SDL/SDL3/SDL_test_compare.h | 4 +- Source/ThirdParty/SDL/SDL3/SDL_test_crc32.h | 27 +- Source/ThirdParty/SDL/SDL3/SDL_test_font.h | 26 +- Source/ThirdParty/SDL/SDL3/SDL_test_fuzzer.h | 128 +- Source/ThirdParty/SDL/SDL3/SDL_test_harness.h | 55 +- Source/ThirdParty/SDL/SDL3/SDL_test_log.h | 16 +- Source/ThirdParty/SDL/SDL3/SDL_test_md5.h | 29 +- Source/ThirdParty/SDL/SDL3/SDL_test_memory.h | 10 +- Source/ThirdParty/SDL/SDL3/SDL_thread.h | 39 +- Source/ThirdParty/SDL/SDL3/SDL_time.h | 37 +- Source/ThirdParty/SDL/SDL3/SDL_timer.h | 10 +- Source/ThirdParty/SDL/SDL3/SDL_touch.h | 1 - Source/ThirdParty/SDL/SDL3/SDL_version.h | 3 +- Source/ThirdParty/SDL/SDL3/SDL_video.h | 676 +-- Source/ThirdParty/SDL/SDL3/SDL_vulkan.h | 24 +- .../Tools/Flax.Build/Deps/Dependencies/SDL.cs | 6 +- 72 files changed, 9446 insertions(+), 3207 deletions(-) create mode 100644 Source/ThirdParty/SDL/SDL3/SDL_gpu.h create mode 100644 Source/ThirdParty/SDL/SDL3/SDL_process.h diff --git a/Source/Engine/Platform/SDL/SDLInput.cpp b/Source/Engine/Platform/SDL/SDLInput.cpp index 696795c0f..2dd870399 100644 --- a/Source/Engine/Platform/SDL/SDLInput.cpp +++ b/Source/Engine/Platform/SDL/SDLInput.cpp @@ -389,7 +389,7 @@ public: SDL_GetGlobalMouseState(&oldPosition.X, &oldPosition.Y); Mouse::SetRelativeMode(relativeMode, window); - if (SDL_SetWindowRelativeMouseMode(static_cast(window)->_window, relativeMode ? SDL_TRUE : SDL_FALSE) != 0) + if (SDL_SetWindowRelativeMouseMode(static_cast(window)->_window, relativeMode) != 0) LOG(Error, "Failed to set mouse relative mode: {0}", String(SDL_GetError())); if (!relativeMode) @@ -441,7 +441,7 @@ public: void OnAxisMotion(SDL_GamepadAxis axis, int16 value); - void OnButtonState(SDL_GamepadButton axis, uint8 state); + void OnButtonState(SDL_GamepadButton axis, bool pressed); // [Gamepad] void SetVibration(const GamepadVibrationState& state) override; @@ -516,7 +516,7 @@ bool SDLInput::HandleEvent(SDLWindow* window, SDL_Event& event) mousePos = SDLInputImpl::Mouse->GetOldMousePosition(); } - if (event.button.state == SDL_RELEASED) + if (!event.button.down) Input::Mouse->OnMouseUp(mousePos, button, window); // Prevent sending multiple mouse down event when double-clicking UI elements else if (event.button.clicks % 2 == 1) @@ -547,7 +547,7 @@ bool SDLInput::HandleEvent(SDLWindow* window, SDL_Event& event) // TODO: scancode support KeyboardKeys key = SDL_TO_FLAX_KEYS_MAP[event.key.scancode]; //event.key.mod - if (event.key.state == SDL_RELEASED) + if (!event.key.down) Input::Keyboard->OnKeyUp(key, window); else Input::Keyboard->OnKeyDown(key, window); @@ -581,7 +581,7 @@ bool SDLInput::HandleEvent(SDLWindow* window, SDL_Event& event) { SDLGamepad* gamepad = SDLGamepad::GetGamepadById(event.gbutton.which); SDL_GamepadButton button = (SDL_GamepadButton)event.gbutton.button; - gamepad->OnButtonState(button, event.gbutton.state); + gamepad->OnButtonState(button, event.gbutton.down); LOG(Info, "SDL_EVENT_GAMEPAD_BUTTON_"); break; @@ -735,51 +735,51 @@ void SDLGamepad::OnAxisMotion(SDL_GamepadAxis sdlAxis, int16 value) _state.Axis[(int32)axis] = valueNormalized; } -void SDLGamepad::OnButtonState(SDL_GamepadButton sdlButton, uint8 state) +void SDLGamepad::OnButtonState(SDL_GamepadButton sdlButton, bool pressed) { switch (sdlButton) { case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_SOUTH: - _state.Buttons[(int32)GamepadButton::A] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::A] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_EAST: - _state.Buttons[(int32)GamepadButton::B] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::B] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_WEST: - _state.Buttons[(int32)GamepadButton::X] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::X] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_NORTH: - _state.Buttons[(int32)GamepadButton::Y] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::Y] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_LEFT_SHOULDER: - _state.Buttons[(int32)GamepadButton::LeftShoulder] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::LeftShoulder] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER: - _state.Buttons[(int32)GamepadButton::RightShoulder] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::RightShoulder] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_BACK: - _state.Buttons[(int32)GamepadButton::Back] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::Back] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_START: - _state.Buttons[(int32)GamepadButton::Start] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::Start] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_LEFT_STICK: - _state.Buttons[(int32)GamepadButton::LeftThumb] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::LeftThumb] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_RIGHT_STICK: - _state.Buttons[(int32)GamepadButton::RightThumb] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::RightThumb] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_DPAD_UP: - _state.Buttons[(int32)GamepadButton::DPadUp] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::DPadUp] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_DPAD_DOWN: - _state.Buttons[(int32)GamepadButton::DPadDown] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::DPadDown] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_DPAD_LEFT: - _state.Buttons[(int32)GamepadButton::DPadLeft] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::DPadLeft] = pressed; break; case SDL_GamepadButton::SDL_GAMEPAD_BUTTON_DPAD_RIGHT: - _state.Buttons[(int32)GamepadButton::DPadRight] = state == SDL_PRESSED; + _state.Buttons[(int32)GamepadButton::DPadRight] = pressed; break; } } diff --git a/Source/Engine/Platform/SDL/SDLPlatform.Linux.cpp b/Source/Engine/Platform/SDL/SDLPlatform.Linux.cpp index bb5d722b3..12ad07f02 100644 --- a/Source/Engine/Platform/SDL/SDLPlatform.Linux.cpp +++ b/Source/Engine/Platform/SDL/SDLPlatform.Linux.cpp @@ -652,7 +652,7 @@ Array SDLClipboard::GetFiles() return Array(); } -SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) +bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) { const X11::XEvent& event = *(X11::XEvent*)xevent; Window* window; @@ -678,7 +678,7 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) { xDnDRequested = Impl::SelectTargetFromAtoms(xDisplay, targetTypeFiles, event.xclient.data.l[2], event.xclient.data.l[3], event.xclient.data.l[4]); } - return SDL_FALSE; + return false; } else if ((uint32)event.xclient.message_type == (uint32)xAtomXdndPosition) { @@ -713,7 +713,7 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) window->OnDragEnter(&dropData, xDndPos, xDndResult); } } - return SDL_FALSE; + return false; } else if ((uint32)event.xclient.message_type == (uint32)xAtomXdndLeave) { @@ -723,7 +723,7 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) window->_dragOver = false; window->OnDragLeave(); } - return SDL_FALSE; + return false; } else if ((uint32)event.xclient.message_type == (uint32)xAtomXdndDrop) { @@ -750,7 +750,7 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) m.data.l[2] = 0; X11::XSendEvent(xDisplay, event.xclient.data.l[0], 0, NoEventMask, (X11::XEvent*)&m); } - return SDL_FALSE; + return false; } } else if (event.type == SelectionNotify) @@ -788,14 +788,14 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) m.data.l[1] = 1; m.data.l[2] = xAtomXdndActionCopy; XSendEvent(xDisplay, xDndSourceWindow, 0, NoEventMask, (X11::XEvent*)&m); - return SDL_FALSE; + return false; } - return SDL_FALSE; + return false; } else if (event.type == SelectionRequest) { if (event.xselectionrequest.selection != xAtomClipboard) - return SDL_FALSE; + return false; const X11::XSelectionRequestEvent* xsr = &event.xselectionrequest; X11::XSelectionEvent ev = { 0 }; @@ -823,13 +823,13 @@ SDL_bool SDLCALL SDLPlatform::X11EventHook(void *userdata, _XEvent *xevent) ev.property = 0; if ((result & 2) == 0) X11::XSendEvent(xDisplay, ev.requestor, 0, 0, (X11::XEvent*)&ev); - return SDL_FALSE; + return false; } else if (event.type == SelectionClear) - return SDL_FALSE; + return false; else if (event.type == XFixesSelectionNotifyEvent) - return SDL_FALSE; - return SDL_TRUE; + return false; + return true; } int X11ErrorHandler(X11::Display* display, X11::XErrorEvent* event) diff --git a/Source/Engine/Platform/SDL/SDLPlatform.Windows.cpp b/Source/Engine/Platform/SDL/SDLPlatform.Windows.cpp index 719999052..496113bb4 100644 --- a/Source/Engine/Platform/SDL/SDLPlatform.Windows.cpp +++ b/Source/Engine/Platform/SDL/SDLPlatform.Windows.cpp @@ -13,7 +13,7 @@ #include // The events for releasing the mouse during window dragging are missing, handle the mouse release event here -SDL_bool SDLCALL SDLPlatform::EventMessageHook(void* userdata, MSG* msg) +bool SDLCALL SDLPlatform::EventMessageHook(void* userdata, MSG* msg) { #define GET_WINDOW_WITH_HWND(window, hwnd) \ do { \ @@ -38,9 +38,9 @@ SDL_bool SDLCALL SDLPlatform::EventMessageHook(void* userdata, MSG* msg) auto hit = static_cast(msg->wParam); if (SDLPlatform::CheckWindowDragging(window, hit)) - return SDL_FALSE; + return false; } - return SDL_TRUE; + return true; #undef GET_WINDOW_WITH_HWND } diff --git a/Source/Engine/Platform/SDL/SDLPlatform.cpp b/Source/Engine/Platform/SDL/SDLPlatform.cpp index d4cb428a7..acba67ea1 100644 --- a/Source/Engine/Platform/SDL/SDLPlatform.cpp +++ b/Source/Engine/Platform/SDL/SDLPlatform.cpp @@ -69,16 +69,16 @@ bool SDLPlatform::Init() SDL_SetHint(SDL_HINT_WINDOWS_RAW_KEYBOARD, "1"); // Disable SDL clipboard support - SDL_SetEventEnabled(SDL_EVENT_CLIPBOARD_UPDATE, SDL_FALSE); + SDL_SetEventEnabled(SDL_EVENT_CLIPBOARD_UPDATE, false); // Disable SDL drag and drop support - SDL_SetEventEnabled(SDL_EVENT_DROP_FILE, SDL_FALSE); - SDL_SetEventEnabled(SDL_EVENT_DROP_TEXT, SDL_FALSE); - SDL_SetEventEnabled(SDL_EVENT_DROP_BEGIN, SDL_FALSE); - SDL_SetEventEnabled(SDL_EVENT_DROP_COMPLETE, SDL_FALSE); - SDL_SetEventEnabled(SDL_EVENT_DROP_POSITION, SDL_FALSE); + SDL_SetEventEnabled(SDL_EVENT_DROP_FILE, false); + SDL_SetEventEnabled(SDL_EVENT_DROP_TEXT, false); + SDL_SetEventEnabled(SDL_EVENT_DROP_BEGIN, false); + SDL_SetEventEnabled(SDL_EVENT_DROP_COMPLETE, false); + SDL_SetEventEnabled(SDL_EVENT_DROP_POSITION, false); - if (SDL_InitSubSystem(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD) < 0) + if (!SDL_InitSubSystem(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD)) Platform::Fatal(String::Format(TEXT("Failed to initialize SDL: {0}."), String(SDL_GetError()))); if (InitPlatform()) @@ -122,7 +122,7 @@ void SDLPlatform::Tick() { Float2 mousePos; auto buttons = SDL_GetGlobalMouseState(&mousePos.X, &mousePos.Y); - if (!(buttons & SDL_BUTTON(SDL_BUTTON_LEFT))) + if (!(buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT))) { Window* window = nullptr; WindowsManager::WindowsLocker.Lock(); diff --git a/Source/Engine/Platform/SDL/SDLPlatform.h b/Source/Engine/Platform/SDL/SDLPlatform.h index 47aabb1b0..5e4f001c2 100644 --- a/Source/Engine/Platform/SDL/SDLPlatform.h +++ b/Source/Engine/Platform/SDL/SDLPlatform.h @@ -47,9 +47,9 @@ private: #endif static bool HandleEvent(SDL_Event& event); #if PLATFORM_WINDOWS - static int __cdecl EventMessageHook(void* userdata, MSG* msg); + static bool __cdecl EventMessageHook(void* userdata, MSG* msg); #elif PLATFORM_LINUX - static int __cdecl X11EventHook(void *userdata, _XEvent *xevent); + static bool __cdecl X11EventHook(void *userdata, _XEvent *xevent); #endif public: diff --git a/Source/Engine/Platform/SDL/SDLWindow.cpp b/Source/Engine/Platform/SDL/SDLWindow.cpp index bbf19c571..aed9efb9f 100644 --- a/Source/Engine/Platform/SDL/SDLWindow.cpp +++ b/Source/Engine/Platform/SDL/SDLWindow.cpp @@ -38,7 +38,7 @@ namespace { SDLWindow* LastEventWindow = nullptr; - static SDL_Cursor* Cursors[SDL_NUM_SYSTEM_CURSORS] = { nullptr }; + static SDL_Cursor* Cursors[SDL_SYSTEM_CURSOR_COUNT] = { nullptr }; } void* GetNativeWindowPointer(SDL_Window* window); @@ -201,17 +201,17 @@ SDLWindow::SDLWindow(const CreateWindowSettings& settings) // It should be noted that SDL creates the window in client-space coordinates (ignoring window decorations) SDL_PropertiesID props = SDL_CreateProperties(); - SDL_SetNumberProperty(props, "flags", flags); + SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER, flags); SDL_SetStringProperty(props, SDL_PROP_WINDOW_CREATE_TITLE_STRING, settings.Title.ToStringAnsi().Get()); SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_X_NUMBER, x); SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_Y_NUMBER, y); SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER, windowWidth); SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER, windowHeight); - SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN, SDL_TRUE); + SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN, true); if ((flags & SDL_WINDOW_TOOLTIP) != 0) - SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN, SDL_TRUE); + SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN, true); else if ((flags & SDL_WINDOW_POPUP_MENU) != 0) - SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN, SDL_TRUE); + SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN, true); if (_settings.Parent != nullptr) SDL_SetPointerProperty(props, SDL_PROP_WINDOW_CREATE_PARENT_POINTER, _settings.Parent->_window); @@ -561,7 +561,7 @@ void SDLWindow::HandleEvent(SDL_Event& event) if (pos.X < rect.x || pos.Y < rect.y || size.X > rect.w || size.Y > rect.h) { // Disable resizable flag so SDL updates the client rectangle to expected values during WM_NCCALCSIZE - SDL_SetWindowResizable(_window, SDL_FALSE); + SDL_SetWindowResizable(_window, false); SDL_MaximizeWindow(_window); // Set the internal floating window rectangle to expected position @@ -572,7 +572,7 @@ void SDLWindow::HandleEvent(SDL_Event& event) SDL_PumpEvents(); // Restore previous values - SDL_SetWindowResizable(_window, SDL_TRUE); + SDL_SetWindowResizable(_window, true); SetClientBounds(_cachedClientRectangle); } } @@ -756,11 +756,11 @@ void SDLWindow::Show() // Reused top-most windows (DockHintWindow) doesn't stay on top for some reason if (_settings.IsTopmost && _settings.Type != WindowType::Tooltip) - SDL_SetWindowAlwaysOnTop(_window, SDL_TRUE); + SDL_SetWindowAlwaysOnTop(_window, true); if (_isTrackingMouse) { - if (SDL_CaptureMouse(SDL_TRUE) != 0) + if (SDL_CaptureMouse(true) != 0) { if (!SDLPlatform::UsesWayland()) // Suppress "That operation is not supported" errors LOG(Warning, "SDL_CaptureMouse: {0}", String(SDL_GetError())); @@ -811,7 +811,7 @@ void SDLWindow::SetBorderless(bool isBorderless, bool maximized) if (isBorderless) { - SDL_SetWindowBordered(_window, !isBorderless ? SDL_TRUE : SDL_FALSE); + SDL_SetWindowBordered(_window, !isBorderless ? true : false); if (maximized) SDL_MaximizeWindow(_window); else @@ -819,7 +819,7 @@ void SDLWindow::SetBorderless(bool isBorderless, bool maximized) } else { - SDL_SetWindowBordered(_window, !isBorderless ? SDL_TRUE : SDL_FALSE); + SDL_SetWindowBordered(_window, !isBorderless ? true : false); if (maximized) SDL_MaximizeWindow(_window); else @@ -1108,11 +1108,11 @@ void SDLWindow::SetClientPosition(const Float2& position) void SDLWindow::SetIsFullscreen(bool isFullscreen) { - SDL_SetWindowFullscreen(_window, isFullscreen ? SDL_TRUE : SDL_FALSE); + SDL_SetWindowFullscreen(_window, isFullscreen ? true : false); if (!isFullscreen) { // The window is set to always-on-top for some reason when leaving fullscreen - SDL_SetWindowAlwaysOnTop(_window, SDL_FALSE); + SDL_SetWindowAlwaysOnTop(_window, false); } WindowBase::SetIsFullscreen(isFullscreen); @@ -1232,7 +1232,7 @@ void SDLWindow::StartTrackingMouse(bool useMouseScreenOffset) if (_visible) { - if (SDL_CaptureMouse(SDL_TRUE) != 0) + if (SDL_CaptureMouse(true) != 0) { if (!SDLPlatform::UsesWayland()) // Suppress "That operation is not supported" errors LOG(Warning, "SDL_CaptureMouse: {0}", String(SDL_GetError())); @@ -1253,7 +1253,7 @@ void SDLWindow::EndTrackingMouse() _isHorizontalFlippingMouse = false; _isVerticalFlippingMouse = false; - if (SDL_CaptureMouse(SDL_FALSE) != 0) + if (SDL_CaptureMouse(false) != 0) { if (!SDLPlatform::UsesWayland()) // Suppress "That operation is not supported" errors LOG(Warning, "SDL_CaptureMouse: {0}", String(SDL_GetError())); diff --git a/Source/ThirdParty/SDL/SDL3/SDL.h b/Source/ThirdParty/SDL/SDL3/SDL.h index 4e18f6382..e9f1d6bee 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL.h +++ b/Source/ThirdParty/SDL/SDL3/SDL.h @@ -22,7 +22,7 @@ /** * \file SDL.h * - * Main include header for the SDL library, version 3.1.2 + * Main include header for the SDL library, version 3.1.3 */ #ifndef SDL_h_ @@ -43,6 +43,7 @@ #include #include #include +#include #include #include #include @@ -64,6 +65,7 @@ #include #include #include +#include #include #include #include diff --git a/Source/ThirdParty/SDL/SDL3/SDL_assert.h b/Source/ThirdParty/SDL/SDL3/SDL_assert.h index 346d1e3a4..ada270010 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_assert.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_assert.h @@ -220,7 +220,7 @@ typedef enum SDL_AssertState */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -303,9 +303,6 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * "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. * - * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! - * Please refer to your platform's documentation for how to set it! - * * \param condition boolean value to test. * * \since This macro is available since SDL 3.0.0. @@ -335,9 +332,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * 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. - * - * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! - * Please refer to your platform's documentation for how to set it! + * * * * \param condition boolean value to test. * @@ -366,18 +361,14 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * "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. * - * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! - * Please refer to your platform's documentation for how to set it! - * * \param condition boolean value to test. * * \since This macro is available since SDL 3.0.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) -#endif /* Enable various levels of assertions. */ -#if SDL_ASSERT_LEVEL == 0 /* assertions disabled */ +#elif SDL_ASSERT_LEVEL == 0 /* assertions disabled */ # define SDL_assert(condition) SDL_disabled_assert(condition) # define SDL_assert_release(condition) SDL_disabled_assert(condition) # define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -412,9 +403,6 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * "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. * - * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint! - * Please refer to your platform's documentation for how to set it! - * * \param condition boolean value to test. * * \since This macro is available since SDL 3.0.0. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_atomic.h b/Source/ThirdParty/SDL/SDL3/SDL_atomic.h index fbf01c4bc..e36436f92 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_atomic.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_atomic.h @@ -88,15 +88,14 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -225,8 +224,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -303,9 +302,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * 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_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * 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 @@ -316,14 +316,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * * \since This struct is available since SDL 3.0.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +336,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \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.0.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -362,9 +363,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \since This function is available since SDL 3.0.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -379,9 +380,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \since This function is available since SDL 3.0.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -402,7 +403,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -418,7 +419,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +430,102 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***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 SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * * \since This macro is available since SDL 3.0.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + * \sa SDL_AddAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable to be modified. + * \param oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable to be modified. + * \param v the desired value. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a pointer to an SDL_AtomicU32 variable. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +535,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \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.0.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPtr - * \sa SDL_AtomicSetPtr + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -474,10 +561,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \since This function is available since SDL 3.0.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPtr + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPtr(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -492,10 +579,10 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPtr(void **a, void *v); * * \since This function is available since SDL 3.0.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPtr + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPtr(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_audio.h b/Source/ThirdParty/SDL/SDL3/SDL_audio.h index f25959c3b..41477d7ca 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_audio.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_audio.h @@ -94,7 +94,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -127,6 +126,7 @@ extern "C" { */ typedef enum SDL_AudioFormat { + SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */ SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */ /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */ SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */ @@ -143,17 +143,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -531,14 +532,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -658,8 +659,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -668,7 +669,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -686,8 +687,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -696,7 +697,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -709,7 +710,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * @@ -718,7 +719,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -752,8 +753,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * 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 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * 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. * @@ -766,8 +767,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. @@ -776,7 +777,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -823,8 +824,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -834,7 +835,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -844,8 +845,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -855,7 +856,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -952,8 +953,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. @@ -962,9 +963,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, - SDL_AudioSpec *src_spec, - SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -984,8 +983,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. @@ -995,9 +994,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, - const SDL_AudioSpec *src_spec, - const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1030,8 +1027,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. @@ -1041,7 +1038,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1077,8 +1074,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \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 0 on successor a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. @@ -1087,7 +1084,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1174,8 +1171,8 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. Don't change the @@ -1186,7 +1183,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1221,8 +1218,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStrea * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. Don't change the @@ -1233,7 +1230,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStrea * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1249,8 +1246,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStre * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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 @@ -1263,7 +1260,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStre * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1280,8 +1277,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, * \param stream the stream the audio is being requested from. * \param buf a buffer to fill with audio data. * \param len the maximum number of bytes to fill. - * \returns the number of bytes read from the stream or a negative error code - * on failure; call SDL_GetError() for more information. + * \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 @@ -1309,7 +1306,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * clamped. * * \param stream the audio stream to query. - * \returns the number of converted/resampled bytes available. + * \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. * @@ -1324,6 +1322,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * 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. @@ -1341,7 +1345,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * clamped. * * \param stream the audio stream to query. - * \returns the number of bytes queued. + * \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. * @@ -1362,8 +1367,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -1371,7 +1376,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1380,8 +1385,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); * stream until more is added. * * \param stream the audio stream to clear. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -1392,7 +1397,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1407,8 +1412,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -1416,7 +1421,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1427,8 +1432,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stre * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -1436,7 +1441,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stre * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); /** * Lock an audio stream for serialized access. @@ -1455,8 +1460,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *str * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -1464,7 +1469,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *str * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1473,8 +1478,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. @@ -1483,7 +1488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1558,13 +1563,12 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * 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 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. This only fails if `stream` - * is NULL. + * \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. * @@ -1572,7 +1576,7 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1612,9 +1616,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. This only fails if `stream` - * is NULL. + * \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. * @@ -1622,7 +1625,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1791,14 +1794,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1853,21 +1856,21 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \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 0 on success. `audio_buf` will be filled with a pointer to an + * \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 -1 if the .WAV file cannot be opened, uses - * an unknown data format, or is corrupt; call SDL_GetError() for - * more information. + * 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. @@ -1879,9 +1882,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool closeio, - SDL_AudioSpec * spec, Uint8 ** audio_buf, - Uint32 * audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1889,7 +1890,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1899,13 +1900,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns 0 on success. `audio_buf` will be filled with a pointer to an + * \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 -1 if the .WAV file cannot be opened, uses - * an unknown data format, or is corrupt; call SDL_GetError() for - * more information. + * 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. @@ -1917,8 +1918,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec, - Uint8 ** audio_buf, Uint32 * audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1947,17 +1947,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * sp * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_MixAudio(Uint8 * dst, - const Uint8 * src, - SDL_AudioFormat format, - Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1980,20 +1977,27 @@ extern SDL_DECLSPEC int SDLCALL SDL_MixAudio(Uint8 * dst, * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, - const Uint8 *src_data, - int src_len, - const SDL_AudioSpec *dst_spec, - Uint8 **dst_data, - int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +/** + * Get the human readable name of an audio format. + * + * \param format the audio format to query. + * \returns the human readable name of the specified audio format or + * "SDL_AUDIO_UNKNOWN" if the format isn't recognized. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); /** * Get the appropriate memset value for silencing an audio format. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h b/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h index f418c6109..acf99284c 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_begin_code.h @@ -53,7 +53,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +70,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Source/ThirdParty/SDL/SDL3/SDL_bits.h b/Source/ThirdParty/SDL/SDL3/SDL_bits.h index 72be08272..15548bc66 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_bits.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_bits.h @@ -120,8 +120,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * 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 @@ -129,18 +128,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_camera.h b/Source/ThirdParty/SDL/SDL3/SDL_camera.h index 46dcee1de..db2eb6940 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_camera.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_camera.h @@ -33,8 +33,11 @@ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,8 +51,7 @@ extern "C" { * * If the device is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 1 and increments from there. The value 0 is an - * invalid ID. + * The value 0 is an invalid ID. * * \since This datatype is available since SDL 3.0.0. * @@ -367,15 +369,15 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * 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 -1, 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_IsCameraApproved() - * occasionally until it returns non-zero. + * 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_IsCameraApproved() occasionally until it returns non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -383,7 +385,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -447,8 +449,6 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \param camera opened camera device. * \param frame the video frame surface to release. - * \returns 0 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. * @@ -456,7 +456,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \sa SDL_AcquireCameraFrame */ -extern SDL_DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame); +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame); /** * Use this function to shut down camera processing and close the camera diff --git a/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h b/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h index ccd32011c..94d8c0edf 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_clipboard.h @@ -46,15 +46,15 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. @@ -76,28 +76,28 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. @@ -120,15 +120,14 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -185,8 +184,8 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \param userdata an opaque pointer that will be forwarded to the callbacks. * \param mime_types a list of mime-types that are being offered. * \param num_mime_types the number of mime-types in the mime_types list. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -194,19 +193,19 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -231,15 +230,30 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s * Query whether there is data in the clipboard for the provided mime type. * * \param mime_type the mime type to check for data for. - * \returns SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \param num_mime_types a pointer filled with the number of mime types, may + * be NULL. + * \returns a null terminated array of strings with mime types, or NULL on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h b/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h index e7ced26d8..ef4a90c69 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_cpuinfo.h @@ -54,7 +54,7 @@ extern "C" { #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * 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 @@ -62,7 +62,7 @@ extern "C" { * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -82,29 +82,29 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * * \since This function is available since SDL 3.0.0. * @@ -113,14 +113,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * * \since This function is available since SDL 3.0.0. * @@ -129,14 +129,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * * \since This function is available since SDL 3.0.0. * @@ -145,14 +145,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * * \since This function is available since SDL 3.0.0. * @@ -161,14 +161,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * * \since This function is available since SDL 3.0.0. * @@ -177,49 +177,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +228,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +253,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,12 +265,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_dialog.h b/Source/ThirdParty/SDL/SDL3/SDL_dialog.h index 8a198a844..a2e328396 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_dialog.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_dialog.h @@ -28,6 +28,7 @@ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include #include @@ -132,14 +133,14 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * the selected filter. * \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. + * \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 SDL_DialogFileFilter's. May be NULL. Not all + * \param filters a list of SDL_DialogFileFilter's, may be NULL. Not all * platforms support this option, and platforms that do support * it may allow the user to ignore the filters. * \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 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. * @@ -150,7 +151,7 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their @@ -189,14 +190,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * the selected filter. * \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. + * \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 SDL_DialogFileFilter's. May be NULL. Not all + * \param filters a list of SDL_DialogFileFilter's, may be NULL. Not all * platforms support this option, and platforms that do support * it may allow the user to ignore the filters. * \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 default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * * \since This function is available since SDL 3.0.0. * @@ -240,10 +241,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * argument is always -1 for SDL_ShowOpenFolderDialog. * \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. + * \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 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. * @@ -253,7 +254,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +262,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_error.h b/Source/ThirdParty/SDL/SDL3/SDL_error.h index 75e8370b1..9256ff297 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_error.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_error.h @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,25 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns -1. + * \returns false. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ClearError * \sa SDL_GetError */ -extern SDL_DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns -1. + * \returns false. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -114,14 +134,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns 0. + * \returns true. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions diff --git a/Source/ThirdParty/SDL/SDL3/SDL_events.h b/Source/ThirdParty/SDL/SDL3/SDL_events.h index 6e5a305e5..fc175df8a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_events.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_events.h @@ -28,17 +28,21 @@ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,25 +52,6 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * @@ -151,8 +136,6 @@ typedef enum SDL_EventType in an event watcher, the window handle is still valid and can still be used to retrieve any userdata associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ - SDL_EVENT_WINDOW_PEN_ENTER, /**< Window has gained focus of the pressure-sensitive pen with ID "data1" */ - SDL_EVENT_WINDOW_PEN_LEAVE, /**< Window has lost focus of the pressure-sensitive pen with ID "data1" */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN, SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_HDR_STATE_CHANGED, @@ -227,11 +210,14 @@ typedef enum SDL_EventType SDL_EVENT_SENSOR_UPDATE = 0x1200, /**< A sensor was updated */ /* Pressure-sensitive pen events */ - SDL_EVENT_PEN_DOWN = 0x1300, /**< Pressure-sensitive pen touched drawing surface */ + SDL_EVENT_PEN_PROXIMITY_IN = 0x1300, /**< Pressure-sensitive pen has become available */ + SDL_EVENT_PEN_PROXIMITY_OUT, /**< Pressure-sensitive pen has become unavailable */ + SDL_EVENT_PEN_DOWN, /**< Pressure-sensitive pen touched drawing surface */ SDL_EVENT_PEN_UP, /**< Pressure-sensitive pen stopped touching drawing surface */ - SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen moved, or angle/pressure changed */ SDL_EVENT_PEN_BUTTON_DOWN, /**< Pressure-sensitive pen button pressed */ SDL_EVENT_PEN_BUTTON_UP, /**< Pressure-sensitive pen button released */ + SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen is moving on the tablet */ + SDL_EVENT_PEN_AXIS, /**< Pressure-sensitive pen angle/pressure/etc changed */ /* Camera hotplug events */ SDL_EVENT_CAMERA_DEVICE_ADDED = 0x1400, /**< A new camera device is available */ @@ -341,8 +327,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -379,7 +365,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -426,7 +415,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -445,9 +434,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -465,7 +454,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -546,7 +535,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -611,7 +600,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -675,7 +664,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -714,67 +703,118 @@ typedef struct SDL_TouchFingerEvent SDL_WindowID windowID; /**< The window underneath the finger, if any */ } SDL_TouchFingerEvent; - /** - * Pressure-sensitive pen touched or stopped touching surface (event.ptip.*) + * Pressure-sensitive pen proximity event structure (event.pmotion.*) + * + * When a pen becomes visible to the system (it is close enough to a tablet, + * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's + * ID. This ID is valid until the pen leaves proximity again (has been removed + * from the tablet's area, the tablet has been unplugged, etc). If the same + * pen reenters proximity again, it will be given a new ID. + * + * Note that "proximity" means "close enough for the tablet to know the tool + * is there." The pen touching and lifting off from the tablet while not + * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * * \since This struct is available since SDL 3.0.0. */ -typedef struct SDL_PenTipEvent +typedef struct SDL_PenProximityEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_PenID which; /**< The pen instance id */ +} SDL_PenProximityEvent; + +/** + * Pressure-sensitive pen motion event structure (event.pmotion.*) + * + * Depending on the hardware, you may get motion events when the pen is not + * touching a tablet, for tracking a pen even when it isn't drawing. You + * should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check + * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when + * dealing with pen motion. + * + * \since This struct is available since SDL 3.0.0. + */ +typedef struct SDL_PenMotionEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ +} SDL_PenMotionEvent; + +/** + * Pressure-sensitive pen touched event structure (event.ptouch.*) + * + * These events come when a pen touches a surface (a tablet, etc), or lifts + * off from one. + * + * \since This struct is available since SDL 3.0.0. + */ +typedef struct SDL_PenTouchEvent { SDL_EventType type; /**< SDL_EVENT_PEN_DOWN or SDL_EVENT_PEN_UP */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ - Uint8 tip; /**< SDL_PEN_TIP_INK when using a regular pen tip, or SDL_PEN_TIP_ERASER if the pen is being used as an eraser (e.g., flipped to use the eraser tip) */ - Uint8 state; /**< SDL_PRESSED on SDL_EVENT_PEN_DOWN and SDL_RELEASED on SDL_EVENT_PEN_UP */ - Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.), SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ - float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per SDL_PenAxis) */ -} SDL_PenTipEvent; - -/** - * Pressure-sensitive pen motion / pressure / angle event structure - * (event.pmotion.*) - * - * \since This struct is available since SDL 3.0.0. - */ -typedef struct SDL_PenMotionEvent -{ - SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ - Uint32 reserved; - Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with pen focus, if any */ - SDL_PenID which; /**< The pen instance id */ - Uint8 padding1; - Uint8 padding2; - Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.), SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */ - float x; /**< X coordinate, relative to window */ - float y; /**< Y coordinate, relative to window */ - float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per SDL_PenAxis) */ -} SDL_PenMotionEvent; + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ +} SDL_PenTouchEvent; /** * Pressure-sensitive pen button event structure (event.pbutton.*) * + * This is for buttons on the pen itself that the user might click. The pen + * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. + * * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_PenButtonEvent { - SDL_EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */ + SDL_EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_PenID which; /**< The pen instance id */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + Uint8 button; /**< The pen button index (first button is 1). */ + bool down; /**< true if the button is pressed */ +} SDL_PenButtonEvent; + +/** + * Pressure-sensitive pen pressure / angle event structure (event.paxis.*) + * + * You might get some of these events even if the pen isn't touching the + * tablet. + * + * \since This struct is available since SDL 3.0.0. + */ +typedef struct SDL_PenAxisEvent +{ + SDL_EventType type; /**< SDL_EVENT_PEN_AXIS */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ - Uint8 button; /**< The pen button index (1 represents the pen tip for compatibility with mouse events) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.), SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */ + SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ - float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per SDL_PenAxis) */ -} SDL_PenButtonEvent; + SDL_PenAxis axis; /**< Axis that has changed */ + float value; /**< New value of axis */ +} SDL_PenAxisEvent; /** * An event used to drop text or request a file open by the system @@ -894,9 +934,11 @@ typedef union SDL_Event SDL_QuitEvent quit; /**< Quit request event data */ SDL_UserEvent user; /**< Custom event data */ SDL_TouchFingerEvent tfinger; /**< Touch finger event data */ - SDL_PenTipEvent ptip; /**< Pen tip touching or leaving drawing surface */ - SDL_PenMotionEvent pmotion; /**< Pen change in position, pressure, or angle */ - SDL_PenButtonEvent pbutton; /**< Pen button press */ + SDL_PenProximityEvent pproximity; /**< Pen proximity event data */ + SDL_PenTouchEvent ptouch; /**< Pen tip touching event data */ + SDL_PenMotionEvent pmotion; /**< Pen motion event data */ + SDL_PenButtonEvent pbutton; /**< Pen button event data */ + SDL_PenAxisEvent paxis; /**< Pen axis event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -947,11 +989,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -963,7 +1011,9 @@ typedef enum SDL_EventAction * 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. + * 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. @@ -985,8 +1035,8 @@ typedef enum SDL_EventAction * 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 a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the number of events actually stored or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -1004,14 +1054,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1023,14 +1073,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1117,8 +1167,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * * \since This function is available since SDL 3.0.0. * @@ -1126,7 +1175,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1139,8 +1188,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -1148,7 +1197,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1167,8 +1216,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * * \since This function is available since SDL 3.0.0. * @@ -1176,7 +1225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1200,9 +1249,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns 1 on success, 0 if the event was filtered, or a negative error - * code on failure; call SDL_GetError() for more information. A - * common reason for error is the event queue being full. + * \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. * * \since This function is available since SDL 3.0.0. * @@ -1210,7 +1259,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1218,8 +1267,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE to disallow it. - * When used with SDL_AddEventWatch, the return value is ignored. + * \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 @@ -1230,16 +1280,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** * Set up a filter to process all events before they change internal state and * are posted to the internal event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be added - * to the internal queue. If it returns SDL_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. + * 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! @@ -1289,13 +1339,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1317,17 +1367,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. * - * \sa SDL_DelEventWatch + * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1342,11 +1392,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void * * * \sa SDL_AddEventWatch */ -extern SDL_DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, void *userdata); /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * 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 @@ -1372,19 +1422,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event diff --git a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h index 756a52dcc..30bfea0fc 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_filesystem.h @@ -143,19 +143,19 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | 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". * @@ -165,44 +165,30 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ + } SDL_Folder; /** @@ -243,11 +229,11 @@ typedef enum SDL_PathType typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** @@ -263,21 +249,57 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.0.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * \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.0.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. @@ -286,50 +308,96 @@ typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char * callback, called once for each directory entry, until all results have been * provided or the callback returns <= 0. * + * This will return false if there was a system problem in general, or if a + * callback returns -1. A successful return means a callback returned 1 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. + * + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `oldpath`'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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,12 +405,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyFile(const char *oldpath, const char *ne * \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 0 on success or a negative error code if the file doesn't exist, - * or another failure; call SDL_GetError() for more information. + * \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.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_gamepad.h b/Source/ThirdParty/SDL/SDL3/SDL_gamepad.h index cec068446..a919097a9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_gamepad.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_gamepad.h @@ -58,9 +58,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -98,7 +100,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -153,7 +155,7 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -203,7 +205,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -330,8 +332,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \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. * @@ -344,7 +346,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -379,12 +381,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -442,26 +444,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -483,15 +485,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -813,14 +815,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -938,12 +940,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -978,7 +980,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +988,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1096,14 +1097,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1169,28 +1170,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1251,27 +1251,28 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * * \since This function is available since SDL 3.0.0. * @@ -1279,7 +1280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepa * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1288,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1331,12 +1332,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,11 +1354,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, S * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if rumble isn't supported on this gamepad. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1378,14 +1380,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 l * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1400,12 +1402,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1413,12 +1415,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 re * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). diff --git a/Source/ThirdParty/SDL/SDL3/SDL_gpu.h b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h new file mode 100644 index 000000000..7cb5bcb20 --- /dev/null +++ b/Source/ThirdParty/SDL/SDL3/SDL_gpu.h @@ -0,0 +1,3712 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2024 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as 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 data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use 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_AcquireGPUSwapchainTexture() 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 + * 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 + * [satellite single-header library](https://github.com/libsdl-org/SDL_gpu_shadercross + * ) + * for performing runtime shader cross-compilation. + * + * 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) + * . + */ + +#ifndef SDL_gpu_h_ +#define SDL_gpu_h_ + +#include +#include +#include +#include +#include +#include + +#include +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* Type Declarations */ + +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.0.0 + */ +typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_SetGPUBufferName + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ +typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ +typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTexture + * \sa SDL_SetGPUTextureName + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ +typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ +typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ +typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ +typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ +typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should acquire and submit a command + * buffer on the same thread. As long as you satisfy this requirement, all + * functionality related to command buffers is thread-safe. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ +typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ +typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ +typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ +typedef struct SDL_GPUFence SDL_GPUFence; + +/** + * Specifies the primitive topology of a graphics pipeline. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUPrimitiveType +{ + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ +} SDL_GPUPrimitiveType; + +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_BeginGPURenderPass + */ +typedef enum SDL_GPULoadOp +{ + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ +} SDL_GPULoadOp; + +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_BeginGPURenderPass + */ +typedef enum SDL_GPUStoreOp +{ + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ +} SDL_GPUStoreOp; + +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUIndexElementSize +{ + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ +} SDL_GPUIndexElementSize; + +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE + * + * For SAMPLER usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM + * + * For COLOR_TARGET usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * + * For STORAGE usages, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT + * + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or + * D32_SFLOAT_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.0.0 + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat + */ +typedef enum SDL_GPUTextureFormat +{ + SDL_GPU_TEXTUREFORMAT_INVALID, + + /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, + SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, + SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, + SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + /* Compressed Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, + /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, + /* Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, + /* Unsigned Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_UINT, + SDL_GPU_TEXTUREFORMAT_R8G8_UINT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT, + SDL_GPU_TEXTUREFORMAT_R16_UINT, + SDL_GPU_TEXTUREFORMAT_R16G16_UINT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, + /* SRGB Unsigned Normalized Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, + /* Compressed SRGB Unsigned Normalized Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, + /* Depth Formats */ + SDL_GPU_TEXTUREFORMAT_D16_UNORM, + SDL_GPU_TEXTUREFORMAT_D24_UNORM, + SDL_GPU_TEXTUREFORMAT_D32_FLOAT, + SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT +} SDL_GPUTextureFormat; + +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTexture + */ +typedef Uint32 SDL_GPUTextureUsageFlags; + +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTexture + */ +typedef enum SDL_GPUTextureType +{ + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ +} SDL_GPUTextureType; + +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ +typedef enum SDL_GPUSampleCount +{ + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ +} SDL_GPUSampleCount; + + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.0.0 + */ +typedef enum SDL_GPUCubeMapFace +{ + SDL_GPU_CUBEMAPFACE_POSITIVEX, + SDL_GPU_CUBEMAPFACE_NEGATIVEX, + SDL_GPU_CUBEMAPFACE_POSITIVEY, + SDL_GPU_CUBEMAPFACE_NEGATIVEY, + SDL_GPU_CUBEMAPFACE_POSITIVEZ, + SDL_GPU_CUBEMAPFACE_NEGATIVEZ +} SDL_GPUCubeMapFace; + +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUBuffer + */ +typedef Uint32 SDL_GPUBufferUsageFlags; + +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTransferBuffer + */ +typedef enum SDL_GPUTransferBufferUsage +{ + SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, + SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD +} SDL_GPUTransferBufferUsage; + +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUShader + */ +typedef enum SDL_GPUShaderStage +{ + SDL_GPU_SHADERSTAGE_VERTEX, + SDL_GPU_SHADERSTAGE_FRAGMENT +} SDL_GPUShaderStage; + +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUShader + */ +typedef Uint32 SDL_GPUShaderFormat; + +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_0 shaders for D3D11. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUVertexElementFormat +{ + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + + /* 32-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_INT, + SDL_GPU_VERTEXELEMENTFORMAT_INT2, + SDL_GPU_VERTEXELEMENTFORMAT_INT3, + SDL_GPU_VERTEXELEMENTFORMAT_INT4, + + /* 32-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_UINT, + SDL_GPU_VERTEXELEMENTFORMAT_UINT2, + SDL_GPU_VERTEXELEMENTFORMAT_UINT3, + SDL_GPU_VERTEXELEMENTFORMAT_UINT4, + + /* 32-bit Floats */ + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3, + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4, + + /* 8-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2, + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4, + + /* 8-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2, + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4, + + /* 8-bit Signed Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4_NORM, + + /* 8-bit Unsigned Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM, + + /* 16-bit Signed Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2, + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4, + + /* 16-bit Unsigned Integers */ + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2, + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4, + + /* 16-bit Signed Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4_NORM, + + /* 16-bit Unsigned Normalized */ + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2_NORM, + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4_NORM, + + /* 16-bit Floats */ + SDL_GPU_VERTEXELEMENTFORMAT_HALF2, + SDL_GPU_VERTEXELEMENTFORMAT_HALF4 +} SDL_GPUVertexElementFormat; + +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUVertexInputRate +{ + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ +} SDL_GPUVertexInputRate; + +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUFillMode +{ + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ +} SDL_GPUFillMode; + +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUCullMode +{ + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ +} SDL_GPUCullMode; + +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUFrontFace +{ + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ +} SDL_GPUFrontFace; + +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUCompareOp +{ + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ +} SDL_GPUCompareOp; + +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUStencilOp +{ + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ +} SDL_GPUStencilOp; + +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUBlendOp +{ + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ +} SDL_GPUBlendOp; + +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef enum SDL_GPUBlendFactor +{ + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ +} SDL_GPUBlendFactor; + +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef Uint8 SDL_GPUColorComponentFlags; + +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUFilter +{ + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ +} SDL_GPUFilter; + +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUSamplerMipmapMode +{ + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ +} SDL_GPUSamplerMipmapMode; + +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUSampler + */ +typedef enum SDL_GPUSamplerAddressMode +{ + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ +} SDL_GPUSamplerAddressMode; + +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * Note that this value affects the behavior of + * SDL_AcquireGPUSwapchainTexture. 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. When using + * this present mode, AcquireGPUSwapchainTexture will block if too many + * frames are in flight. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. When using this mode, AcquireGPUSwapchainTexture will return NULL + * if too many frames are in flight. + * - 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. When using + * this mode, AcquireGPUSwapchainTexture will return NULL if too many frames + * are in flight. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_AcquireGPUSwapchainTexture + */ +typedef enum SDL_GPUPresentMode +{ + SDL_GPU_PRESENTMODE_VSYNC, + SDL_GPU_PRESENTMODE_IMMEDIATE, + SDL_GPU_PRESENTMODE_MAILBOX +} SDL_GPUPresentMode; + +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB + * encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in + * nonlinear sRGB encoding. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_SFLOAT swapchain. Pixel values are in + * extended linear encoding. + * - HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * PQ ST2048 encoding. + * + * \since This enum is available since SDL 3.0.0 + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_AcquireGPUSwapchainTexture + */ +typedef enum SDL_GPUSwapchainComposition +{ + SDL_GPU_SWAPCHAINCOMPOSITION_SDR, + SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, + SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 +} SDL_GPUSwapchainComposition; + +/* Structures */ + +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_SetGPUViewport + */ +typedef struct SDL_GPUViewport +{ + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ +} SDL_GPUViewport; + +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ +typedef struct SDL_GPUTextureTransferInfo +{ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ +} SDL_GPUTextureTransferInfo; + +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ +typedef struct SDL_GPUTransferBufferLocation +{ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ +} SDL_GPUTransferBufferLocation; + +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CopyGPUTextureToTexture + */ +typedef struct SDL_GPUTextureLocation +{ + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ +} SDL_GPUTextureLocation; + +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ +typedef struct SDL_GPUTextureRegion +{ + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ +} SDL_GPUTextureRegion; + +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitRegion +{ + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ +} SDL_GPUBlitRegion; + +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CopyGPUBufferToBuffer + */ +typedef struct SDL_GPUBufferLocation +{ + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ +} SDL_GPUBufferLocation; + +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ +typedef struct SDL_GPUBufferRegion +{ + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ +} SDL_GPUBufferRegion; + +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID). If your shader depends on these variables, the + * correlating draw call parameter MUST be 0. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_DrawGPUPrimitivesIndirect + */ +typedef struct SDL_GPUIndirectDrawCommand +{ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ +} SDL_GPUIndirectDrawCommand; + +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID). If your shader depends on these variables, the + * correlating draw call parameter MUST be 0. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ +typedef struct SDL_GPUIndexedIndirectDrawCommand +{ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ +} SDL_GPUIndexedIndirectDrawCommand; + +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_DispatchGPUComputeIndirect + */ +typedef struct SDL_GPUIndirectDispatchCommand +{ + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ +} SDL_GPUIndirectDispatchCommand; + +/* State structures */ + +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUSampler + */ +typedef struct SDL_GPUSamplerCreateInfo +{ + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUSamplerCreateInfo; + +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription +{ + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; + +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexAttribute +{ + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ +} SDL_GPUVertexAttribute; + +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUVertexInputState +{ + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ +} SDL_GPUVertexInputState; + +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUDepthStencilState + */ +typedef struct SDL_GPUStencilOpState +{ + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ +} SDL_GPUStencilOpState; + +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState +{ + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUShader + */ +typedef struct SDL_GPUShaderCreateInfo +{ + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUShaderCreateInfo; + +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTexture + */ +typedef struct SDL_GPUTextureCreateInfo +{ + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUTextureCreateInfo; + +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" + +/** + * A structure specifying the parameters of a buffer. + * + * 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.0.0 + * + * \sa SDL_CreateGPUBuffer + */ +typedef struct SDL_GPUBufferCreateInfo +{ + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUBufferCreateInfo; + +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUTransferBuffer + */ +typedef struct SDL_GPUTransferBufferCreateInfo +{ + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUTransferBufferCreateInfo; + +/* Pipeline state structures */ + +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on 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.0.0 + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPURasterizerState +{ + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPURasterizerState; + +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUMultisampleState +{ + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUMultisampleState; + +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUDepthStencilState +{ + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUDepthStencilState; + +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription +{ + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; + +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo +{ + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; + +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUGraphicsPipeline + */ +typedef struct SDL_GPUGraphicsPipelineCreateInfo +{ + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUGraphicsPipelineCreateInfo; + +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_CreateGPUComputePipeline + */ +typedef struct SDL_GPUComputePipelineCreateInfo +{ + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ + + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ +} SDL_GPUComputePipelineCreateInfo; + +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo +{ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; + +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo +{ + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; + +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; + +/* Binding structs */ + +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffers + */ +typedef struct SDL_GPUBufferBinding +{ + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffers. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ +} SDL_GPUBufferBinding; + +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ +typedef struct SDL_GPUTextureSamplerBinding +{ + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ +} SDL_GPUTextureSamplerBinding; + +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding +{ + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; + +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.0.0 + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding +{ + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; + +/* Functions */ + +/* Device */ + +/** + * Checks for GPU runtime support. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats + */ +extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( + SDL_GPUShaderFormat format_flags, + bool debug_mode, + const char *name); + +/** + * Creates a GPU context. + * + * These are the supported properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties + * and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy + * efficiency over maximum GPU performance, defaults to false. + * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to + * use, if a specific one is desired. + * + * These are the current shader format properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOL`: The app is able to + * provide shaders for an NDA platform. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * provide SPIR-V shaders if applicable. + * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide + * DXBC shaders if applicable + * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * provide DXIL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide + * MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * provide Metal shader libraries if applicable. + * + * With the D3D12 renderer: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to + * use for all vertex semantics, default is "TEXCOORD". + * + * \param props the properties to use. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties + */ +extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( + SDL_PropertiesID props); + +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOL "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" + +/** + * Destroys a GPU context previously returned by SDL_CreateGPUDevice. + * + * \param device a GPU Context to destroy. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); + +/** + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. + * + * \param device a GPU context to query. + * \returns the name of the device's driver, or NULL on error. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); + +/* State Creation */ + +/** + * Creates a pipeline object to be used in a compute workflow. + * + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. + * + * For SPIR-V shaders, use the following resource sets: + * + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Write-only storage textures, followed by write-only storage buffers + * - 2: Uniform buffers + * + * For DXBC Shader Model 5_0 shaders, use the following register order: + * + * - t registers: Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - u registers: Write-only storage textures, followed by write-only storage + * buffers + * - b registers: Uniform buffers + * + * For 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): Write-only storage textures, followed by write-only + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by write-only storage buffers, + * followed by write-only storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by write-only storage textures + * + * \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.0.0. + * + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ +extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( + SDL_GPUDevice *device, + const SDL_GPUComputePipelineCreateInfo *createinfo); + +/** + * Creates a pipeline object to be used in a graphics workflow. + * + * \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.0.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ +extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( + SDL_GPUDevice *device, + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +/** + * Creates a sampler object to be used when binding textures in a graphics + * workflow. + * + * \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.0.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseSampler + */ +extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( + SDL_GPUDevice *device, + const SDL_GPUSamplerCreateInfo *createinfo); + +/** + * 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 Shader Model 5_0 shaders, use the following register order: + * + * - t registers: Sampled textures, followed by storage textures, followed by + * storage buffers + * - s registers: Samplers with indices corresponding to the sampled textures + * - b registers: Uniform buffers + * + * For 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_GPUPipeline. + * + * \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.0.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ +extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( + SDL_GPUDevice *device, + const SDL_GPUShaderCreateInfo *createinfo); + +/** + * Creates a texture object to be used in graphics or compute workflows. + * + * The contents of this texture are undefined until data is written to the + * texture. + * + * Note that certain combinations of usage flags are invalid. For example, a + * texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags. + * + * If you request a sample count higher than the hardware supports, the + * implementation will automatically fall back to the highest available sample + * count. + * + * \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.0.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + * \sa SDL_GPUTextureSupportsFormat + */ +extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( + SDL_GPUDevice *device, + const SDL_GPUTextureCreateInfo *createinfo); + +/** + * 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. + * + * \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.0.0. + * + * \sa SDL_SetGPUBufferName + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ +extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( + SDL_GPUDevice *device, + const SDL_GPUBufferCreateInfo *createinfo); + +/** + * Creates a transfer buffer to be used when uploading to or downloading from + * graphics resources. + * + * \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.0.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ +extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( + SDL_GPUDevice *device, + const SDL_GPUTransferBufferCreateInfo *createinfo); + +/* Debug Naming */ + +/** + * Sets an arbitrary string constant to label a buffer. + * + * Useful for debugging. + * + * \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. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( + SDL_GPUDevice *device, + SDL_GPUBuffer *buffer, + const char *text); + +/** + * Sets an arbitrary string constant to label a texture. + * + * Useful for debugging. + * + * \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. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( + SDL_GPUDevice *device, + SDL_GPUTexture *texture, + const char *text); + +/** + * Inserts an arbitrary string label into the command buffer callstream. + * + * Useful for debugging. + * + * \param command_buffer a command buffer. + * \param text a UTF-8 string constant to insert as the label. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( + SDL_GPUCommandBuffer *command_buffer, + const char *text); + +/** + * Begins a debug group with an arbitary name. + * + * Used for denoting groups of calls when viewing the command buffer + * callstream in a graphics debugging tool. + * + * Each call to SDL_PushGPUDebugGroup must have a corresponding call to + * SDL_PopGPUDebugGroup. + * + * On some backends (e.g. Metal), pushing a debug group during a + * render/blit/compute pass will create a group that is scoped to the native + * pass rather than the command buffer. For best results, if you push a debug + * group during a pass, always pop it in the same pass. + * + * \param command_buffer a command buffer. + * \param name a UTF-8 string constant that names the group. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_PopGPUDebugGroup + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( + SDL_GPUCommandBuffer *command_buffer, + const char *name); + +/** + * Ends the most-recently pushed debug group. + * + * \param command_buffer a command buffer. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_PushGPUDebugGroup + */ +extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( + SDL_GPUCommandBuffer *command_buffer); + +/* Disposal */ + +/** + * Frees the given texture as soon as it is safe to do so. + * + * You must not reference the texture after calling this function. + * + * \param device a GPU context. + * \param texture a texture to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( + SDL_GPUDevice *device, + SDL_GPUTexture *texture); + +/** + * Frees the given sampler as soon as it is safe to do so. + * + * You must not reference the sampler after calling this function. + * + * \param device a GPU context. + * \param sampler a sampler to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( + SDL_GPUDevice *device, + SDL_GPUSampler *sampler); + +/** + * Frees the given buffer as soon as it is safe to do so. + * + * You must not reference the buffer after calling this function. + * + * \param device a GPU context. + * \param buffer a buffer to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( + SDL_GPUDevice *device, + SDL_GPUBuffer *buffer); + +/** + * Frees the given transfer buffer as soon as it is safe to do so. + * + * You must not reference the transfer buffer after calling this function. + * + * \param device a GPU context. + * \param transfer_buffer a transfer buffer to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer); + +/** + * Frees the given compute pipeline as soon as it is safe to do so. + * + * You must not reference the compute pipeline after calling this function. + * + * \param device a GPU context. + * \param compute_pipeline a compute pipeline to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( + SDL_GPUDevice *device, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Frees the given shader as soon as it is safe to do so. + * + * You must not reference the shader after calling this function. + * + * \param device a GPU context. + * \param shader a shader to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( + SDL_GPUDevice *device, + SDL_GPUShader *shader); + +/** + * Frees the given graphics pipeline as soon as it is safe to do so. + * + * You must not reference the graphics pipeline after calling this function. + * + * \param device a GPU context. + * \param graphics_pipeline a graphics pipeline to be destroyed. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( + SDL_GPUDevice *device, + SDL_GPUGraphicsPipeline *graphics_pipeline); + +/** + * Acquire a command buffer. + * + * This command buffer is managed by the implementation and should not be + * freed by the user. The command buffer may only be used on the thread it was + * acquired on. The command buffer should be submitted on the thread it was + * acquired on. + * + * \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.0.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( + SDL_GPUDevice *device); + +/* + * 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 (vertex, fragment, 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. + */ + +/** + * Pushes data to a vertex uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/** + * Pushes data to a fragment uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/** + * Pushes data to a uniform slot on the command buffer. + * + * Subsequent draw calls will use this uniform data. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, + const void *data, + Uint32 length); + +/* + * 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. + * GPUTransferBuffer, GPUBuffer, and 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 MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. + * 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. + */ + +/* Graphics State */ + +/** + * Begins a render pass on a command buffer. + * + * A render pass consists of a set of texture subresources (or depth slices in + * the 3D texture case) which will be rendered to during the render pass, + * along with corresponding clear values and load/store operations. All + * operations related to graphics pipelines must take place inside of a render + * pass. A default viewport and scissor state are automatically set when this + * is called. You cannot begin another render pass, or begin a compute pass or + * copy pass until you have ended the render pass. + * + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. + * \returns a render pass handle. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_EndGPURenderPass + */ +extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); + +/** + * Binds a graphics pipeline on a render pass to be used in rendering. + * + * A graphics pipeline must be bound before making any draw calls. + * + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); + +/** + * Sets the current viewport state on a command buffer. + * + * \param render_pass a render pass handle. + * \param viewport the viewport to set. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); + +/** + * Sets the current scissor state on a command buffer. + * + * \param render_pass a render pass handle. + * \param scissor the scissor area to set. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); + +/** + * Binds vertex buffers on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); + +/** + * Binds an index buffer on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); + +/** + * Binds texture-sampler pairs for use on the vertex shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures for use on the vertex shader. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers for use on the vertex shader. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/** + * Binds texture-sampler pairs for use on the fragment shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures for use on the fragment shader. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers for use on the fragment shader. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/* Drawing */ + +/** + * Draws data using bound graphics state with an index buffer and instancing + * enabled. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID). If your shader depends on these variables, the + * correlating draw call parameter MUST be 0. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); + +/** + * Draws data using bound graphics state. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID). If your shader depends on these variables, the + * correlating draw call parameter MUST be 0. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); + +/** + * Draws data using bound graphics state and with draw parameters set from a + * buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( + SDL_GPURenderPass *render_pass, + SDL_GPUBuffer *buffer, + Uint32 offset, + Uint32 draw_count); + +/** + * Draws data using bound graphics state with an index buffer enabled and with + * draw parameters set from a buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( + SDL_GPURenderPass *render_pass, + SDL_GPUBuffer *buffer, + Uint32 offset, + Uint32 draw_count); + +/** + * Ends the given render pass. + * + * All bound graphics state on the render pass command buffer is unset. The + * render pass handle is now invalid. + * + * \param render_pass a render pass handle. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( + SDL_GPURenderPass *render_pass); + +/* Compute Pass */ + +/** + * Begins a compute pass on a command buffer. + * + * A compute pass is defined by a set of texture subresources and buffers that + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. + * + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! + * + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. + * \returns a compute pass handle. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_EndGPUComputePass + */ +extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); + +/** + * Binds a compute pipeline on a command buffer for use in compute dispatch. + * + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); + +/** + * Binds storage textures as readonly for use on the compute pipeline. + * + * These textures must have been created with + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); + +/** + * Binds storage buffers as readonly for use on the compute pipeline. + * + * These buffers must have been created with + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); + +/** + * Dispatches compute work. + * + * You must not call this function before binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); + +/** + * Dispatches compute work with parameters set from a buffer. + * + * The buffer layout should match the layout of + * SDL_GPUIndirectDispatchCommand. You must not call this function before + * binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param buffer a buffer containing dispatch parameters. + * \param offset the offset to start reading from the dispatch buffer. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( + SDL_GPUComputePass *compute_pass, + SDL_GPUBuffer *buffer, + Uint32 offset); + +/** + * Ends the current compute pass. + * + * All bound compute state on the command buffer is unset. The compute pass + * handle is now invalid. + * + * \param compute_pass a compute pass handle. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( + SDL_GPUComputePass *compute_pass); + +/* TransferBuffer Data */ + +/** + * Maps a transfer buffer into application address space. + * + * You must unmap the transfer buffer before encoding upload commands. + * + * \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.0.0. + */ +extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); + +/** + * Unmaps a previously mapped transfer buffer. + * + * \param device a GPU context. + * \param transfer_buffer a previously mapped transfer buffer. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( + SDL_GPUDevice *device, + SDL_GPUTransferBuffer *transfer_buffer); + +/* Copy Pass */ + +/** + * Begins a copy pass on a command buffer. + * + * All operations related to copying to or from buffers or textures take place + * inside a copy pass. You must not begin another copy pass, or a render pass + * or compute pass before ending the copy pass. + * + * \param command_buffer a command buffer. + * \returns a copy pass handle. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Uploads data from a transfer buffer to a texture. + * + * The upload occurs on the GPU timeline. You may assume that the upload has + * finished in subsequent commands. + * + * You must align the data in the transfer buffer to a multiple of the texel + * size of the texture format. + * + * \param copy_pass a copy pass handle. + * \param source the source transfer buffer with image layout information. + * \param destination the destination texture region. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); + +/* Uploads data from a TransferBuffer to a Buffer. */ + +/** + * 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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); + +/** + * Performs a texture-to-texture copy. + * + * This copy occurs on the GPU timeline. You may assume the copy has finished + * in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source a source texture region. + * \param destination a destination texture region. + * \param w the width of the region to copy. + * \param h the height of the region to copy. + * \param d the depth of the region to copy. + * \param cycle if true, cycles the destination texture if the destination + * texture is bound, otherwise overwrites the data. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, + Uint32 w, + Uint32 h, + Uint32 d, + bool cycle); + +/* Copies data from a buffer to a buffer. */ + +/** + * 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.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, + Uint32 size, + bool cycle); + +/** + * Copies data from a texture to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source texture region. + * \param destination the destination transfer buffer with image layout + * information. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); + +/** + * Copies data from a buffer to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source buffer with offset and size. + * \param destination the destination transfer buffer with offset. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); + +/** + * Ends the current copy pass. + * + * \param copy_pass a copy pass handle. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( + SDL_GPUCopyPass *copy_pass); + +/** + * Generates mipmaps for the given texture. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command_buffer. + * \param texture a texture with more than 1 mip level. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_GPUTexture *texture); + +/** + * Blits from a source texture region to a destination texture region. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); + +/* Submission/Presentation */ + +/** + * Determines whether a swapchain composition is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUSwapchainComposition swapchain_composition); + +/** + * Determines whether a presentation mode is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUPresentMode present_mode); + +/** + * Claims a window, creating a swapchain structure for it. + * + * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created + * the window. + * + * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and + * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_ReleaseWindowFromGPUDevice + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Unclaims a window, destroying its swapchain structure. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_ClaimWindowForGPUDevice + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Changes the swapchain parameters for the given claimed window. + * + * This function will fail if the requested present mode or swapchain + * composition are unsupported by the device. Check if the parameters are + * supported via SDL_WindowSupportsGPUPresentMode / + * SDL_WindowSupportsGPUSwapchainComposition prior to calling this function. + * + * SDL_GPU_PRESENTMODE_VSYNC and SDL_GPU_SWAPCHAINCOMPOSITION_SDR are always + * supported. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( + SDL_GPUDevice *device, + SDL_Window *window, + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * 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.0.0. + */ +extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Acquire a texture to use in presentation. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. The swapchain texture handle can be filled in + * with NULL under certain conditions. This is not necessarily an error. If + * this function returns false then there is an error. + * + * 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. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_ClaimWindowForGPUDevice + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_GetWindowSizeInPixels + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * 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.0.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Submits a command buffer so its commands can be processed on the GPU, and + * acquires a fence associated with the command buffer. + * + * You must release this fence when it is no longer needed or it will cause a + * leak. It is invalid to use the command buffer after this is called. + * + * This must be called from the thread the command buffer was acquired on. + * + * All commands in the submission are guaranteed to begin executing before any + * command in a subsequent submission begins executing. + * + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_ReleaseGPUFence + */ +extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( + SDL_GPUCommandBuffer *command_buffer); + +/** + * Blocks the thread until the GPU is completely idle. + * + * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_WaitForGPUFences + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( + SDL_GPUDevice *device); + +/** + * Blocks the thread until the given fences are signaled. + * + * \param device a GPU context. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_WaitForGPUIdle + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( + SDL_GPUDevice *device, + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); + +/** + * Checks the status of a fence. + * + * \param device a GPU context. + * \param fence a fence. + * \returns true if the fence is signaled, false if it is not. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( + SDL_GPUDevice *device, + SDL_GPUFence *fence); + +/** + * Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence. + * + * \param device a GPU context. + * \param fence a fence. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( + SDL_GPUDevice *device, + SDL_GPUFence *fence); + +/* Format Info */ + +/** + * Obtains the texel block size for a texture format. + * + * \param format the texture format you want to know the texel size of. + * \returns the texel block size of the texture format. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_UploadToGPUTexture + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( + SDL_GPUTextureFormat format); + +/** + * Determines whether a texture format is supported for a given type and + * usage. + * + * \param device a GPU context. + * \param format the texture format to check. + * \param type the type of texture (2D, 3D, Cube). + * \param usage a bitmask of all usage scenarios to check. + * \returns whether the texture format is supported for this type and usage. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( + SDL_GPUDevice *device, + SDL_GPUTextureFormat format, + SDL_GPUTextureType type, + SDL_GPUTextureUsageFlags usage); + +/** + * Determines if a sample count for a texture format is supported. + * + * \param device a GPU context. + * \param format the texture format to check. + * \param sample_count the sample count to check. + * \returns a hardware-specific version of min(preferred, possible). + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( + SDL_GPUDevice *device, + SDL_GPUTextureFormat format, + SDL_GPUSampleCount sample_count); + +#ifdef SDL_PLATFORM_GDK + +/** + * Call this to suspend GPU operation on Xbox when you receive the + * SDL_EVENT_DID_ENTER_BACKGROUND event. + * + * Do NOT call any SDL_GPU functions after calling this function! This must + * also be called before calling SDL_GDKSuspendComplete. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_AddEventWatch + */ +extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); + +/** + * Call this to resume GPU operation on Xbox when you receive the + * SDL_EVENT_WILL_ENTER_FOREGROUND event. + * + * When resuming, this function MUST be called before calling any other + * SDL_GPU functions. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_AddEventWatch + */ +extern SDL_DECLSPEC void SDLCALL SDL_GDKResumeGPU(SDL_GPUDevice *device); + +#endif /* SDL_PLATFORM_GDK */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#include + +#endif /* SDL_gpu_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_guid.h b/Source/ThirdParty/SDL/SDL3/SDL_guid.h index 285b2376e..d45a3c365 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_guid.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_guid.h @@ -32,7 +32,6 @@ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_haptic.h b/Source/ThirdParty/SDL/SDL3/SDL_haptic.h index 1d0a54efe..58b5b1c99 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_haptic.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_haptic.h @@ -48,15 +48,15 @@ * SDL_free(haptics); * } * if (haptic == NULL) - * return -1; + * return; * * // Initialize simple rumble - * if (SDL_InitHapticRumble(haptic) != 0) - * return -1; + * if (!SDL_InitHapticRumble(haptic)) + * return; * * // Play effect at 50% strength for 2 seconds - * if (SDL_PlayHapticRumble(haptic, 0.5, 2000) != 0) - * return -1; + * if (!SDL_PlayHapticRumble(haptic, 0.5, 2000)) + * return; * SDL_Delay(2000); * * // Clean up @@ -66,7 +66,7 @@ * Complete example: * * ```c - * int test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return -1; // Most likely joystick isn't haptic + * 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 -1; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return 0; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.0.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -919,8 +918,7 @@ typedef union SDL_HapticEffect * * If the haptic device is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 1 and increments from there. The value 0 is an - * invalid ID. + * The value 0 is an invalid ID. * * \since This datatype is available since SDL 3.0.0. */ @@ -1026,13 +1024,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * * \since This function is available since SDL 3.0.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1051,13 +1049,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * * \since This function is available since SDL 3.0.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1117,8 +1115,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query maximum playing effects. * \returns the number of effects the haptic device can play at the same time - * or a negative error code on failure; call SDL_GetError() for more - * information. + * or -1 on failure; call SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -1148,8 +1145,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * SDL_HapticDirection effect. * * \param haptic the SDL_Haptic device to query. - * \returns the number of axes on success or a negative error code on failure; - * call SDL_GetError() for more information. + * \returns the number of axes on success or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. */ @@ -1160,14 +1157,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1175,8 +1172,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \param haptic an SDL_Haptic device to create the effect on. * \param effect an SDL_HapticEffect structure containing the properties of * the effect to create. - * \returns the ID of the effect on success or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the ID of the effect on success or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -1198,15 +1195,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1221,8 +1218,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int e * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1230,22 +1227,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int e * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC int SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1269,12 +1266,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns 0 if it isn't playing, 1 if it is playing, or a negative error - * code on failure; call SDL_GetError() for more information. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC int SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1288,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC int SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1307,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC int SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1326,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC int SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,47 +1341,47 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC int SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * * \since This function is available since SDL 3.0.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1390,7 +1389,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *hapti * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC int SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1397,28 @@ extern SDL_DECLSPEC int SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC int SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC int SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_hidapi.h b/Source/ThirdParty/SDL/SDL3/SDL_hidapi.h index 66bea9da3..730fdee42 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_hidapi.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_hidapi.h @@ -537,11 +537,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *de /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_hints.h b/Source/ThirdParty/SDL/SDL3/SDL_hints.h index 7f4391c4c..4550090a1 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_hints.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_hints.h @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -39,8 +37,8 @@ #ifndef SDL_hints_h_ #define SDL_hints_h_ -#include #include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -139,7 +137,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_APP_ID "SDL_APP_ID" +#define SDL_HINT_APP_ID "SDL_APP_ID" /** * A variable setting the application name. @@ -227,7 +225,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" +#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" /** * A variable controlling the default audio channel count. @@ -473,7 +471,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" +#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" /** * A variable controlling whether SDL updates sensor state when getting input @@ -488,7 +486,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" +#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" /** * Prevent SDL from using version 4 of the bitmap header when saving BMPs. @@ -642,7 +640,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" +#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" /** * Specify the CSS selector used for the "default" window/canvas. @@ -675,7 +673,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" +#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" /** * A variable that controls whether the on-screen keyboard should be shown @@ -733,7 +731,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" +#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" /** * A variable controlling whether raising the window should be done more @@ -753,7 +751,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" +#define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" /** * A variable controlling how 3D acceleration is used to accelerate the SDL @@ -774,7 +772,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" +#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" /** * A variable that lets you manually hint extra gamecontroller db entries. @@ -900,7 +898,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" +#define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" /** * This variable sets the description of the TextInput window on GDK @@ -1006,6 +1004,20 @@ extern "C" { */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" +/** + * A variable that specifies a GPU backend to use. + * + * By default, SDL will try all available GPU backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. + * + * This hint should be set before SDL_GPUSelectBackend() is called. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" + /** * A variable to control whether SDL_hid_enumerate() enumerates all HID * devices or only controllers. @@ -1226,6 +1238,21 @@ extern "C" { */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" +/** + * A variable controlling whether GameInput should be used for controller + * handling on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used. (default) + * - "1": GameInput is used. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" + /** * A variable containing a list of devices known to have a GameCube form * factor. @@ -1625,6 +1652,17 @@ extern "C" { */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1701,8 +1739,8 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * * This hint should be set before enumerating controllers. * @@ -1741,7 +1779,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" /** * A variable controlling whether the HIDAPI driver for XBox 360 controllers @@ -1758,7 +1796,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" /** * A variable controlling whether the player LEDs should be lit to indicate @@ -1790,7 +1828,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" /** * A variable controlling whether the HIDAPI driver for XBox One controllers @@ -1807,7 +1845,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" +#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" /** * A variable controlling whether the Home button LED should be turned on when @@ -1952,7 +1990,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" +#define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" /** * A variable controlling whether the ROG Chakram mice should show up as @@ -2110,7 +2148,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2167,7 +2205,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" +#define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" /** * A variable controlling the default SDL log levels. @@ -2193,7 +2231,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_LOGGING "SDL_LOGGING" +#define SDL_HINT_LOGGING "SDL_LOGGING" /** * A variable controlling whether to force the application to become the @@ -2209,7 +2247,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" +#define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" /** * A variable that determines whether Ctrl+Click should generate a right-click @@ -2285,7 +2323,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" +#define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" /** * A variable setting the double click radius, in pixels. @@ -2294,7 +2332,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" +#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" /** * A variable setting the double click time, in milliseconds. @@ -2303,14 +2341,15 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. * - * When this hint is set and the mouse cursor is hidden, SDL will emulate - * mouse warps using relative mouse mode. This can provide smoother and more + * When this hint is set, the mouse cursor is hidden, and multiple warps to + * the window center occur within a short time period, SDL will emulate mouse + * warps using relative mouse mode. This can provide smoother and more * reliable mouse motion for some older games, which continuously calculate * the distance travelled by the mouse pointer and warp it back to the center * of the window, rather than using relative mouse motion. @@ -2318,9 +2357,8 @@ extern "C" { * Note that relative mouse mode may have different mouse acceleration * behavior than pointer warps. * - * If your game or application needs to warp the mouse cursor while hidden for - * other purposes, such as drawing a software cursor, it should disable this - * hint. + * 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: * @@ -2359,7 +2397,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" +#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" /** * A variable controlling whether relative mouse mode constrains the mouse to @@ -2380,7 +2418,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" +#define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" /** * A variable controlling whether relative mouse mode is implemented using @@ -2395,7 +2433,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" +#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" /** * A variable setting the scale for mouse motion, in floating point, when the @@ -2405,7 +2443,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" +#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" /** * A variable controlling whether the system mouse acceleration curve is used @@ -2424,7 +2462,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" +#define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" /** * A variable controlling whether a motion event should be generated for mouse @@ -2443,7 +2481,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" +#define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" /** * A variable controlling whether the hardware cursor stays visible when @@ -2461,24 +2499,24 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" +#define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" /** * Controls how often SDL issues cursor confinement commands to the operating * system while relative mode is active, in case the desired confinement state * became out-of-sync due to interference from other running programs. * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. + * The variable can be integers representing milliseconds between each + * refresh. A value of zero means SDL will not automatically refresh the + * confinement. The default value varies depending on the operating system, + * this variable might not have any effects on inapplicable platforms such as + * those without a cursor. * * This hint can be set anytime. * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" +#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" /** * A variable controlling whether mouse events should generate synthetic touch @@ -2495,7 +2533,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" +#define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" /** * A variable controlling whether the keyboard should be muted on the console. @@ -2528,7 +2566,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" +#define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" /** * Specify the OpenGL library to load. @@ -2572,7 +2610,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +#define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" /** * A variable controlling which orientations are allowed on iOS/Android. @@ -2593,54 +2631,6 @@ extern "C" { */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" -/** - * A variable controlling whether pen mouse button emulation triggers only - * when the pen touches the tablet surface. - * - * The variable can be set to the following values: - * - * - "0": The pen reports mouse button press/release immediately when the pen - * button is pressed/released, and the pen tip touching the surface counts - * as left mouse button press. - * - "1": Mouse button presses are sent when the pen first touches the tablet - * (analogously for releases). Not pressing a pen button simulates mouse - * button 1, pressing the first pen button simulates mouse button 2 etc.; it - * is not possible to report multiple buttons as pressed at the same time. - * (default) - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_PEN_DELAY_MOUSE_BUTTON "SDL_PEN_DELAY_MOUSE_BUTTON" - -/** - * A variable controlling whether to treat pen movement as separate from mouse - * movement. - * - * By default, pens report both SDL_MouseMotionEvent and SDL_PenMotionEvent - * updates (analogously for button presses). This hint allows decoupling mouse - * and pen updates. - * - * This variable toggles between the following behaviour: - * - * - "0": Pen acts as a mouse with mouse ID SDL_PEN_MOUSEID. (default) Use - * case: client application is not pen aware, user wants to use pen instead - * of mouse to interact. - * - "1": Pen reports mouse clicks and movement events but does not update - * SDL-internal mouse state (buttons pressed, current mouse location). Use - * case: client application is not pen aware, user frequently alternates - * between pen and "real" mouse. - * - "2": Pen reports no mouse events. Use case: pen-aware client application - * uses this hint to allow user to toggle between pen+mouse mode ("2") and - * pen-only mode ("1" or "0"). - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_PEN_NOT_MOUSE "SDL_PEN_NOT_MOUSE" - /** * A variable controlling the use of a sentinel event when polling the event * queue. @@ -2727,7 +2717,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" +#define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" /** * A variable controlling whether to enable Vulkan Validation Layers. @@ -2741,7 +2731,36 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" +#define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" + +/** + * A variable controlling whether to create the GPU device in debug mode. + * + * This variable can be set to the following values: + * + * - "0": Disable debug mode use (default) + * - "1": Enable debug mode use + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" + +/** + * A variable controlling whether to prefer a low-power GPU on multi-GPU + * systems. + * + * This variable can be set to the following values: + * + * - "0": Prefer high-performance GPU (default) + * - "1": Prefer low-power GPU + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" /** * A variable specifying which render driver to use. @@ -2769,7 +2788,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" +#define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" /** * A variable controlling how the 2D render API renders lines. @@ -2819,7 +2838,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" +#define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" /** * A variable to control whether the return key on the soft keyboard should @@ -2887,7 +2906,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" +#define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" /** * Specify an "activity name" for screensaver inhibition. @@ -2981,7 +3000,7 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * * \since This hint is available since SDL 3.0.0. */ @@ -2989,26 +3008,26 @@ extern "C" { /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * 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_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" +#define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" /** * A variable that controls the timer resolution, in milliseconds. @@ -3043,7 +3062,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" +#define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" /** * A variable controlling whether trackpads should be treated as touch @@ -3093,7 +3112,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" /** * Tell the video driver that we only want a double buffer. @@ -3116,7 +3135,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" +#define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" /** * A variable that specifies a video backend to use. @@ -3191,7 +3210,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" /** * A variable controlling whether fullscreen windows are minimized when they @@ -3207,7 +3226,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" +#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" /** * A variable controlling whether the offscreen video driver saves output @@ -3389,7 +3408,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" +#define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" /** * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint @@ -3423,7 +3442,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" +#define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" /** * A variable controlling whether SDL uses DirectColor visuals. @@ -3448,7 +3467,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" +#define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" /** * A variable forcing the visual ID used for X11 display modes. @@ -3466,7 +3485,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" +#define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" /** * A variable controlling whether the X11 XRandR extension should be used. @@ -3480,7 +3499,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" +#define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" /** * A variable controlling whether touch should be enabled on the back panel of @@ -3580,7 +3599,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" +#define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" /** * A variable overriding the display index used in SDL_Vulkan_CreateSurface() @@ -3633,7 +3652,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" +#define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" /** * A variable controlling the maximum number of chunks in a WAVE file. @@ -3645,7 +3664,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" +#define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" /** * A variable controlling how the size of the RIFF chunk affects the loading @@ -3673,7 +3692,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" +#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" /** * A variable controlling how a truncated WAVE file is handled. @@ -3693,7 +3712,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" +#define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" /** * A variable controlling whether the window is activated when the @@ -3710,7 +3729,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" +#define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" /** * A variable controlling whether the window is activated when the @@ -3727,7 +3746,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" +#define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" /** * If set to "0" then never set the top-most flag on an SDL Window even if the @@ -3761,7 +3780,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" +#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" /** * A variable controlling whether SDL generates window-close events for Alt+F4 @@ -3823,6 +3842,22 @@ extern "C" { */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" +/** + * A variable controlling whether GameInput is used for raw keyboard and mouse + * on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used for raw keyboard and mouse events. + * - "1": GameInput is used for raw keyboard and mouse events, if available. + * (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" + /** * A variable controlling whether raw keyboard events are used on Windows. * @@ -3835,7 +3870,7 @@ extern "C" { * * \since This hint is available since SDL 3.0.0. */ -#define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" +#define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" /** * A variable controlling whether SDL uses Kernel Semaphores on Windows. @@ -3912,119 +3947,6 @@ extern "C" { */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4066,7 +3988,7 @@ extern "C" { /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * @@ -4089,6 +4011,31 @@ extern "C" { */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" +/** + * A variable controlling response to SDL_assert failures. + * + * The variable can be set to the following case-sensitive values: + * + * - "abort": Program terminates immediately. + * - "break": Program triggers a debugger breakpoint. + * - "retry": Program reruns the SDL_assert's test again. + * - "ignore": Program continues on, ignoring this assertion failure this + * time. + * - "always_ignore": Program continues on, ignoring this assertion failure + * for the rest of the run. + * + * Note that SDL_SetAssertionHandler offers a programmatic means to deal with + * assertion failures through a callback, and this hint is largely intended to + * be used via environment variables by end users and automated tools. + * + * This hint should be set before an assertion failure is triggered and can be + * changed at any time. + * + * \since This hint is available since SDL 3.0.0. + */ +#define SDL_HINT_ASSERT "SDL_ASSERT" + + /** * An enumeration of hint priorities. * @@ -4101,7 +4048,6 @@ typedef enum SDL_HintPriority SDL_HINT_OVERRIDE } SDL_HintPriority; - /** * Set a hint with a specific priority. * @@ -4112,8 +4058,8 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -4123,9 +4069,7 @@ typedef enum SDL_HintPriority * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC int SDLCALL SDL_SetHintWithPriority(const char *name, - const char *value, - SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4136,8 +4080,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHintWithPriority(const char *name, * * \param name the hint to set. * \param value the value of the hint variable. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -4147,7 +4091,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHintWithPriority(const char *name, * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC int SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4157,8 +4101,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHint(const char *name, const char *value) * change. * * \param name the hint to set. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -4167,7 +4111,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHint(const char *name, const char *value) * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC int SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4202,7 +4146,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * \sa SDL_SetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); +extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); /** * Get the boolean value of a hint variable. @@ -4219,7 +4163,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4240,7 +4184,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * * \sa SDL_AddHintCallback */ -typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); +typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); /** * Add a function to watch a particular hint. @@ -4252,18 +4196,16 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. * - * \sa SDL_DelHintCallback + * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC int SDLCALL SDL_AddHintCallback(const char *name, - SDL_HintCallback callback, - void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4279,7 +4221,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddHintCallback(const char *name, * * \sa SDL_AddHintCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, +extern SDL_DECLSPEC void SDLCALL SDL_RemoveHintCallback(const char *name, SDL_HintCallback callback, void *userdata); diff --git a/Source/ThirdParty/SDL/SDL3/SDL_init.h b/Source/ThirdParty/SDL/SDL3/SDL_init.h index 6b5181600..645dad51f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_init.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_init.h @@ -22,15 +22,36 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ #include #include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -56,7 +77,6 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ #define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ @@ -66,6 +86,38 @@ typedef Uint32 SDL_InitFlags; #define SDL_INIT_SENSOR 0x00008000u /**< `SDL_INIT_SENSOR` implies `SDL_INIT_EVENTS` */ #define SDL_INIT_CAMERA 0x00010000u /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */ +/** + * Return values for optional main callbacks. + * + * Returning SDL_APP_SUCCESS or SDL_APP_FAILURE from SDL_AppInit, + * SDL_AppEvent, or SDL_AppIterate will terminate the program and report + * success/failure to the operating system. What that means is + * platform-dependent. On Unix, for example, on success, the process error + * code will be zero, and on failure it will be 1. This interface doesn't + * allow you to return specific exit codes, just whether there was an error + * generally or not. + * + * Returning SDL_APP_CONTINUE from these functions will let the app continue + * to run. + * + * See + * [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3) + * for complete details. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_AppResult +{ + SDL_APP_CONTINUE, /**< Value that requests that the app continue from the main callbacks. */ + SDL_APP_SUCCESS, /**< Value that requests termination with success from the main callbacks. */ + SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ +} SDL_AppResult; + +typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); +typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate); +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. * @@ -84,7 +136,6 @@ typedef Uint32 SDL_InitFlags; * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events @@ -110,8 +161,8 @@ typedef Uint32 SDL_InitFlags; * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -122,7 +173,7 @@ typedef Uint32 SDL_InitFlags; * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -130,8 +181,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags); * This function and SDL_Init() are interchangeable. * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -139,7 +190,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags); * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC int SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -215,8 +266,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); * hash, or whatever makes sense). * \param appidentifier A unique string in reverse-domain format that * identifies this app ("com.example.mygame2"). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -224,7 +275,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -250,7 +301,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch * 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 + * - `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 @@ -260,16 +311,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch * 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 + * - `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 + * - `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 + * - `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. + * - `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 @@ -277,8 +328,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -287,7 +338,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); #define SDL_PROP_APP_METADATA_NAME_STRING "SDL.app.metadata.name" #define SDL_PROP_APP_METADATA_VERSION_STRING "SDL.app.metadata.version" diff --git a/Source/ThirdParty/SDL/SDL3/SDL_iostream.h b/Source/ThirdParty/SDL/SDL3/SDL_iostream.h index fce0e1245..3c4ffd5b3 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_iostream.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_iostream.h @@ -72,7 +72,7 @@ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * 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.0.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,17 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * 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. * - * \return 0 if successful or -1 on write error when flushing data. + * 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. */ - int (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); + } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -216,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * 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, @@ -230,6 +263,7 @@ typedef struct SDL_IOStream SDL_IOStream; * \since This function is available since SDL 3.0.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -239,6 +273,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -256,6 +291,13 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call @@ -265,6 +307,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -272,6 +315,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -289,6 +335,13 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call @@ -346,20 +399,19 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \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. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -371,21 +423,30 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * 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 0 on success, or -1 if the stream failed to flush to its output - * (e.g. to disk). + * 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 to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC int SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -449,8 +510,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * 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 a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -523,6 +584,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -564,6 +626,24 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -574,9 +654,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \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. * @@ -584,7 +665,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * * \sa SDL_LoadFile */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -618,24 +699,40 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -646,28 +743,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. - * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -678,12 +759,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -694,12 +775,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -710,12 +791,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -726,12 +807,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -742,12 +823,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -758,12 +839,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -774,12 +855,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -790,12 +871,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -806,12 +887,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -822,12 +903,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -842,24 +923,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -871,12 +952,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -888,12 +969,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -904,12 +985,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -920,12 +1001,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -937,12 +1018,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -954,12 +1035,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -970,12 +1051,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -986,12 +1067,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1003,12 +1084,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1020,12 +1101,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1036,12 +1117,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1052,12 +1133,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_joystick.h b/Source/ThirdParty/SDL/SDL3/SDL_joystick.h index 1a1707664..520e6eb07 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_joystick.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_joystick.h @@ -91,8 +91,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * If the joystick is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 1 and increments from there. The value 0 is an - * invalid ID. + * The value 0 is an invalid ID. * * \since This datatype is available since SDL 3.0.0. */ @@ -121,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -161,12 +161,6 @@ typedef enum SDL_JoystickConnectionState #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -190,13 +184,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joyst /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -415,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * * \since This struct is available since SDL 3.0.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -447,17 +444,28 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - int (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - int (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - int (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - int (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - int (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystic * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystic * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joyst * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick * \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 state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joy * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -853,9 +860,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * device and platform. * * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of axis controls/number of axes on success or a - * negative error code on failure; call SDL_GetError() for more - * information. + * \returns the number of axis controls/number of axes on success or -1 on + * failure; call SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -875,8 +881,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * Most joysticks do not have trackballs. * * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of trackballs on success or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the number of trackballs on success or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -891,8 +897,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * Get the number of POV hats on a joystick. * * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of POV hats on success or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the number of POV hats on success or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -907,8 +913,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * Get the number of buttons on a joystick. * * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of buttons on success or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns the number of buttons on success or -1 on failure; call + * SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -933,7 +939,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -942,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -995,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \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 SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1013,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1053,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1076,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns 0, or -1 if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1102,14 +1107,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint1 * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1124,12 +1129,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystic * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1137,12 +1142,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). diff --git a/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h b/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h index d4f9b22cd..f6ab13bb5 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_keyboard.h @@ -31,6 +31,9 @@ #include #include #include +#include +#include +#include #include #include @@ -45,8 +48,7 @@ extern "C" { * * If the keyboard is disconnected and reconnected, it will get a new ID. * - * The ID value starts at 1 and increments from there. The value 0 is an - * invalid ID. + * The value 0 is an invalid ID. * * \since This datatype is available since SDL 3.0.0. */ @@ -57,13 +59,13 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -117,9 +119,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * 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. * @@ -139,7 +141,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. @@ -190,13 +192,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * 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 SDL_TRUE. Otherwise this function simply translates the + * 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 SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * * \since This function is available since SDL 3.0.0. @@ -204,7 +206,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -232,14 +234,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -323,8 +325,8 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * On some platforms using this function shows the screen keyboard. * * \param window the window to enable text input. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -333,7 +335,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC int SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -401,11 +403,11 @@ typedef enum SDL_Capitalization * 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 SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * 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: * @@ -415,8 +417,8 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -425,7 +427,7 @@ typedef enum SDL_Capitalization * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC int SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -437,13 +439,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_StartTextInputWithProperties(SDL_Window *win * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -452,28 +454,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC int SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -486,15 +488,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -506,39 +508,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextInputArea(SDL_Window *window, const S * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_keycode.h b/Source/ThirdParty/SDL/SDL3/SDL_keycode.h index 2d03a3d68..28e40a352 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_keycode.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_keycode.h @@ -123,7 +123,7 @@ typedef Uint32 SDL_Keycode; #define SDLK_RIGHTBRACE 0x0000007du /* '}' */ #define SDLK_TILDE 0x0000007eu /* '~' */ #define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ +#define SDLK_PLUSMINUS 0x000000b1u /* '\xB1' */ #define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ #define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ #define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_loadso.h b/Source/ThirdParty/SDL/SDL3/SDL_loadso.h index ab34a3862..2d49c75fe 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_loadso.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_loadso.h @@ -26,6 +26,14 @@ * * 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 @@ -52,6 +60,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +78,14 @@ extern "C" { * \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.0.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +107,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \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.0.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_log.h b/Source/ThirdParty/SDL/SDL3/SDL_log.h index 078ab9dbe..8feb9e0af 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_log.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_log.h @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * 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, @@ -72,9 +72,9 @@ extern "C" { /** * The predefined log categories * - * By default the application category is enabled at the INFO level, the - * assert category is enabled at the WARN level, test is enabled at the - * VERBOSE level and all other categories are enabled at the ERROR level. + * 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.0.0. */ @@ -89,9 +89,9 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_RENDER, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -120,13 +120,15 @@ typedef enum SDL_LogCategory */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -135,6 +137,8 @@ typedef enum SDL_LogPriority * * \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.0.0. * * \sa SDL_ResetLogPriorities @@ -148,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \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.0.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -163,6 +168,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int 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.0.0. * * \sa SDL_SetLogPriority @@ -174,6 +181,8 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * 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.0.0. * * \sa SDL_SetLogPriorities @@ -191,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC int SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -208,6 +219,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priorit * \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.0.0. * * \sa SDL_LogCritical @@ -216,11 +229,37 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priorit * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -229,6 +268,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \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.0.0. * * \sa SDL_Log @@ -250,6 +291,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \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.0.0. * * \sa SDL_Log @@ -258,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -271,6 +315,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \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.0.0. * * \sa SDL_Log @@ -279,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -292,6 +339,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \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.0.0. * * \sa SDL_Log @@ -301,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -313,6 +363,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \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.0.0. * * \sa SDL_Log @@ -321,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -334,6 +387,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \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.0.0. * * \sa SDL_Log @@ -342,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -356,6 +412,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \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.0.0. * * \sa SDL_Log @@ -364,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -379,6 +438,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \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.0.0. * * \sa SDL_Log @@ -387,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -397,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * 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(). @@ -417,6 +481,8 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \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.0.0. * * \sa SDL_SetLogOutputFunction @@ -429,6 +495,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \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.0.0. * * \sa SDL_GetLogOutputFunction diff --git a/Source/ThirdParty/SDL/SDL3/SDL_main.h b/Source/ThirdParty/SDL/SDL3/SDL_main.h index 0985629a9..e173bd5c6 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_main.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_main.h @@ -48,20 +48,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - Ideally, #include'ing SDL_main.h is enough to get a main() function working. - However, that requires the source file your main() is in to be compiled - as C++ *and* with the /ZW compiler flag. If that's not feasible, add an - otherwise empty .cpp file that only contains `#include ` - and build that with /ZW (still include SDL_main.h in your other file with main()!). - In XAML apps, instead the function SDL_RunApp() must be called with a pointer - to the Direct3D-hosted XAML control passed in as the "reserved" argument. - */ - #define SDL_MAIN_NEEDED - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -188,16 +174,12 @@ #define main SDL_main #endif +#include #include #ifdef __cplusplus extern "C" { #endif -typedef int (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); -typedef int (SDLCALL *SDL_AppIterate_func)(void *appstate); -typedef int (SDLCALL *SDL_AppEvent_func)(void *appstate, const SDL_Event *event); -typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); - /* * You can (optionally!) define SDL_MAIN_USE_CALLBACKS before including * SDL_main.h, and then your application will _not_ have a standard @@ -224,49 +206,6 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); */ #ifdef SDL_MAIN_USE_CALLBACKS -/** - * Value that requests that the app continue from the main callbacks. - * - * If SDL_AppInit, SDL_AppEvent, or SDL_AppIterate returns this value, the - * program will continue to run. This is the normal return value case. - * - * This is always 0; using this macro may be clearer, but is not required. - * - * \since This macro is available since SDL 3.0.0. - */ -#define SDL_APP_CONTINUE 0 - -/** - * Value that requests termination with error from the main callbacks. - * - * If SDL_AppInit, SDL_AppEvent, or SDL_AppIterate returns this value, the - * program will terminate and report failure to the operating system. - * - * What that failure looks like is platform-dependent. On Unix, for example, - * the process error code will be non-zero. - * - * This is always -1; using this macro may be clearer, but is not required. - * - * \since This macro is available since SDL 3.0.0. - */ -#define SDL_APP_FAILURE -1 - -/** - * Value that requests termination with success from the main callbacks. - * - * If SDL_AppInit, SDL_AppEvent, or SDL_AppIterate returns this value, the - * program will terminate and report success to the operating system. - * - * What that success looks like is platform-dependent. On Unix, for example, - * the process error code will be zero. - * - * This is always 1; using this macro may be clearer, but is not required. - * - * \since This macro is available since SDL 3.0.0. - */ -#define SDL_APP_SUCCESS 1 - - /** * App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps. * @@ -311,7 +250,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_AppEvent * \sa SDL_AppQuit */ -extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char *argv[]); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int argc, char *argv[]); /** * App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -359,7 +298,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char * \sa SDL_AppInit * \sa SDL_AppEvent */ -extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); /** * App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -406,7 +345,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate); * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -433,6 +372,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event * resources to it should be cleaned up here. * * \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 This function is not thread safe. * @@ -440,7 +380,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event * * \sa SDL_AppInit */ -extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); +extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate, SDL_AppResult result); #endif /* SDL_MAIN_USE_CALLBACKS */ @@ -525,8 +465,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * 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, -1 on failure; - * SDL_GetError() might have more information on the failure. + * \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. @@ -563,7 +504,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -584,12 +525,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -608,7 +549,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #ifdef SDL_PLATFORM_GDK @@ -630,13 +571,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) + || defined(SDL_PLATFORM_WINDOWS) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ + || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ + || defined(SDL_PLATFORM_EMSCRIPTEN) /* platforms which main (-equivalent) can be implemented in plain C */ #include - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ + #elif 0 /* C++ platforms (currently none, this used to be here for WinRT, but is left for future platforms that might arrive. */ #ifdef __cplusplus #include #else @@ -650,7 +592,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #endif /* __GNUC__ */ #endif /* __cplusplus */ - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif /* C++ platforms */ #endif #endif /* SDL_main_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h b/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h index ad122dfc5..feca572bc 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_main_impl.h @@ -67,7 +67,7 @@ /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -124,71 +124,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #elif defined(SDL_PLATFORM_NGAGE) /* same typedef as in ngage SDKs e32def.h */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h b/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h index 6aa385371..ff22baf94 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_messagebox.h @@ -96,7 +96,7 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** @@ -106,7 +106,7 @@ typedef enum SDL_MessageBoxColorType */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** @@ -154,14 +154,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -196,14 +196,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *mes * \param title uTF-8 title text. * \param message uTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_misc.h b/Source/ThirdParty/SDL/SDL3/SDL_misc.h index 09dec9e06..2d5aa153e 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_misc.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_misc.h @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_mouse.h b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h index 814858ea5..44060091f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mouse.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mouse.h @@ -30,6 +30,7 @@ #include #include +#include #include #include @@ -38,9 +39,26 @@ extern "C" { #endif +/** + * This is a unique ID for a mouse for the time it is connected to the system, + * and is never reused for the lifetime of the application. + * + * If the mouse is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.0.0. + */ typedef Uint32 SDL_MouseID; -typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ +/** + * The structure used to identify an SDL cursor. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.0.0. + */ +typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). @@ -69,7 +87,7 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** @@ -106,12 +124,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -119,13 +137,13 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -176,7 +194,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); * Retrieve the current state of the mouse. * * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the + * tested using the SDL_BUTTON_MASK(X) macro (where `X` is generally 1 for the * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the * mouse cursor position relative to the focus window. You can pass NULL for * either `x` or `y`. @@ -215,7 +233,7 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, flo * \param y filled in with the current Y coord relative to the desktop; can be * NULL. * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * the SDL_BUTTON_MASK(X) macros. * * \since This function is available since SDL 3.0.0. * @@ -228,10 +246,10 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float * * Retrieve the relative state of the mouse. * * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * tested using the `SDL_BUTTON_MASK(X)` macros (where `X` is generally 1 for + * the left, 2 for middle, 3 for the right button), and `x` and `y` are set to + * the mouse deltas since the last call to SDL_GetRelativeMouseState() or + * since event initialization. You can pass NULL for either `x` or `y`. * * \param x a pointer filled with the last recorded x coordinate of the mouse. * \param y a pointer filled with the last recorded y coordinate of the mouse. @@ -278,46 +296,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. * - * While the window has focus and relative mouse mode is enabled, the cursor is hidden, the mouse - * position is constrained to the window, and SDL will report continuous - * relative mouse motion even if the mouse is at the edge of the window. + * 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. * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -355,15 +374,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -421,8 +440,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * 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 size image will be scaled to the appropriate size - * and be used instead. + * 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. @@ -463,14 +483,14 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC int SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -518,41 +538,41 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC int SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h index eea003092..03cb80cfb 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_mutex.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_mutex.h @@ -29,7 +29,9 @@ */ #include +#include #include +#include /******************************************************************************/ /* Enable thread safety attributes only with clang. @@ -115,16 +117,6 @@ extern "C" { #endif -/** - * Synchronization functions return this value if they time out. - * - * Not all functions _can_ time out; some will block indefinitely. - * - * \since This macro is available since SDL 3.0.0. - */ -#define SDL_MUTEX_TIMEDOUT 1 - - /** * \name Mutex functions */ @@ -194,25 +186,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns `SDL_MUTEX_TIMEDOUT` immediately. + * 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 does not fail; if mutex is NULL, it will return 0 immediately - * having locked nothing. If the mutex is valid, this function will always - * either lock the mutex and return 0, or return SDL_MUTEX_TIMEOUT and lock - * nothing. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns 0 or `SDL_MUTEX_TIMEDOUT`. + * \returns true on success, false if the mutex would block. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -278,19 +267,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); */ typedef struct SDL_RWLock SDL_RWLock; -/* - * Synchronization functions return this value if they time out. - * - * Not all functions _can_ time out; some will block indefinitely. - * - * This symbol is just for clarity when dealing with SDL_RWLock - * functions; its value is equivalent to SDL_MUTEX_TIMEOUT. - * - * \since This macro is available since SDL 3.0.0. - */ -#define SDL_RWLOCK_TIMEDOUT SDL_MUTEX_TIMEDOUT - - /** * Create a new read/write lock. * @@ -405,7 +381,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * 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 `SDL_RWLOCK_TIMEDOUT` immediately. + * 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. @@ -413,13 +389,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * 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 does not fail; if rwlock is NULL, it will return 0 - * immediately having locked nothing. If rwlock is valid, this function will - * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT - * and lock nothing. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns 0 or `SDL_RWLOCK_TIMEDOUT`. + * \returns true on success, false if the lock would block. * * \since This function is available since SDL 3.0.0. * @@ -427,13 +400,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, this function returns `SDL_RWLOCK_TIMEDOUT` immediately. + * 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. @@ -446,13 +419,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) * 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 0 - * immediately having locked nothing. If rwlock is valid, this function will - * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT - * and lock nothing. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns 0 or `SDL_RWLOCK_TIMEDOUT`. + * \returns true on success, false if the lock would block. * * \since This function is available since SDL 3.0.0. * @@ -460,7 +430,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -569,17 +539,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. * - * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value or the call is interrupted by a - * signal or error. If the call is successful it will atomically decrement the - * semaphore value. + * This function 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. - * \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.0.0. * @@ -587,7 +554,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); /** * See if a semaphore has a positive value and decrement it if it does. @@ -595,12 +562,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_MUTEX_TIMEDOUT. + * returns false. * * \param sem the semaphore to wait on. - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would - * block, or a negative error code on failure; call SDL_GetError() - * for more information. + * \returns true if the wait succeeds, false if the wait would block. * * \since This function is available since SDL 3.0.0. * @@ -608,21 +573,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. * * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value, the call is interrupted by a - * signal or error, or the specified time has elapsed. If the call is - * successful it will atomically decrement the semaphore value. + * 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. - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not - * succeed in the allotted time, or a negative error code on failure; - * call SDL_GetError() for more information. + * \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.0.0. * @@ -630,14 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. - * \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.0.0. * @@ -645,7 +606,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sin * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); /** * Get the current value of a semaphore. @@ -711,8 +672,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * Restart one of the threads that are waiting on the condition variable. * * \param cond the condition variable to signal. - * \returns 0 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. * @@ -722,14 +681,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * \sa SDL_WaitCondition * \sa SDL_WaitConditionTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_SignalCondition(SDL_Condition *cond); +extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); /** * Restart all threads that are waiting on the condition variable. * * \param cond the condition variable to signal. - * \returns 0 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. * @@ -739,7 +696,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SignalCondition(SDL_Condition *cond); * \sa SDL_WaitCondition * \sa SDL_WaitConditionTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); +extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); /** * Wait until a condition variable is signaled. @@ -758,8 +715,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \param cond the condition variable to wait on. * \param mutex the mutex used to coordinate thread access. - * \returns 0 when it is signaled or a negative error code on failure; call - * SDL_GetError() for more information. * * \threadsafety It is safe to call this function from any thread. * @@ -769,7 +724,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * \sa SDL_SignalCondition * \sa SDL_WaitConditionTimeout */ -extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex *mutex); +extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex *mutex); /** * Wait until a condition variable is signaled or a certain time has passed. @@ -788,9 +743,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if - * the condition is not signaled in the allotted time, or a negative - * error code on failure; call SDL_GetError() for more information. + * \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. * @@ -800,11 +754,156 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC int SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return true; + * } + * + * // 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.0.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_oldnames.h b/Source/ThirdParty/SDL/SDL3/SDL_oldnames.h index cd895d5ea..bd79d594f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_oldnames.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_oldnames.h @@ -38,9 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -72,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -116,6 +122,7 @@ #define SDL_DROPCOMPLETE SDL_EVENT_DROP_COMPLETE #define SDL_DROPFILE SDL_EVENT_DROP_FILE #define SDL_DROPTEXT SDL_EVENT_DROP_TEXT +#define SDL_DelEventWatch SDL_RemoveEventWatch #define SDL_FINGERDOWN SDL_EVENT_FINGER_DOWN #define SDL_FINGERMOTION SDL_EVENT_FINGER_MOTION #define SDL_FINGERUP SDL_EVENT_FINGER_UP @@ -296,6 +303,7 @@ #define SDL_MouseIsHaptic SDL_IsMouseHaptic /* ##SDL_hints.h */ +#define SDL_DelHintCallback SDL_RemoveHintCallback #define SDL_HINT_ALLOW_TOPMOST SDL_HINT_WINDOW_ALLOW_TOPMOST #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT @@ -415,9 +423,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -523,7 +537,6 @@ #define SDL_RenderSetVSync SDL_SetRenderVSync #define SDL_RenderSetViewport SDL_SetRenderViewport #define SDL_RenderWindowToLogical SDL_RenderCoordinatesFromWindow -#define SDL_ScaleModeBest SDL_SCALEMODE_BEST #define SDL_ScaleModeLinear SDL_SCALEMODE_LINEAR #define SDL_ScaleModeNearest SDL_SCALEMODE_NEAREST @@ -555,6 +568,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -577,7 +591,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -620,14 +639,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -658,9 +676,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -692,6 +715,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -736,6 +760,7 @@ #define SDL_DROPCOMPLETE SDL_DROPCOMPLETE_renamed_SDL_EVENT_DROP_COMPLETE #define SDL_DROPFILE SDL_DROPFILE_renamed_SDL_EVENT_DROP_FILE #define SDL_DROPTEXT SDL_DROPTEXT_renamed_SDL_EVENT_DROP_TEXT +#define SDL_DelEventWatch SDL_DelEventWatch_renamed_SDL_RemoveEventWatch #define SDL_FINGERDOWN SDL_FINGERDOWN_renamed_SDL_EVENT_FINGER_DOWN #define SDL_FINGERMOTION SDL_FINGERMOTION_renamed_SDL_EVENT_FINGER_MOTION #define SDL_FINGERUP SDL_FINGERUP_renamed_SDL_EVENT_FINGER_UP @@ -917,6 +942,7 @@ #define SDL_MouseIsHaptic SDL_MouseIsHaptic_renamed_SDL_IsMouseHaptic /* ##SDL_hints.h */ +#define SDL_DelHintCallback SDL_DelHintCallback_renamed_SDL_RemoveHintCallback #define SDL_HINT_ALLOW_TOPMOST SDL_HINT_ALLOW_TOPMOST_renamed_SDL_HINT_WINDOW_ALLOW_TOPMOST #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT @@ -1036,9 +1062,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1144,7 +1176,6 @@ #define SDL_RenderSetVSync SDL_RenderSetVSync_renamed_SDL_SetRenderVSync #define SDL_RenderSetViewport SDL_RenderSetViewport_renamed_SDL_SetRenderViewport #define SDL_RenderWindowToLogical SDL_RenderWindowToLogical_renamed_SDL_RenderCoordinatesFromWindow -#define SDL_ScaleModeBest SDL_ScaleModeBest_renamed_SDL_SCALEMODE_BEST #define SDL_ScaleModeLinear SDL_ScaleModeLinear_renamed_SDL_SCALEMODE_LINEAR #define SDL_ScaleModeNearest SDL_ScaleModeNearest_renamed_SDL_SCALEMODE_NEAREST @@ -1176,6 +1207,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1198,7 +1230,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1241,14 +1278,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS diff --git a/Source/ThirdParty/SDL/SDL3/SDL_opengl_glext.h b/Source/ThirdParty/SDL/SDL3/SDL_opengl_glext.h index ff6ad12ce..fa0f6c2a5 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_opengl_glext.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_opengl_glext.h @@ -9807,15 +9807,15 @@ typedef void (APIENTRYP PFNGLUPLOADGPUMASKNVXPROC) (GLbitfield mask); typedef void (APIENTRYP PFNGLMULTICASTVIEWPORTARRAYVNVXPROC) (GLuint gpu, GLuint first, GLsizei count, const GLfloat *v); typedef void (APIENTRYP PFNGLMULTICASTVIEWPORTPOSITIONWSCALENVXPROC) (GLuint gpu, GLuint index, GLfloat xcoeff, GLfloat ycoeff); typedef void (APIENTRYP PFNGLMULTICASTSCISSORARRAYVNVXPROC) (GLuint gpu, GLuint first, GLsizei count, const GLint *v); -typedef GLuint (APIENTRYP PFNGLASYNCCOPYBUFFERSUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); -typedef GLuint (APIENTRYP PFNGLASYNCCOPYIMAGESUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +typedef GLuint (APIENTRYP PFNGLASYNCCOPYBUFFERSUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +typedef GLuint (APIENTRYP PFNGLASYNCCOPYIMAGESUBDATANVXPROC) (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); #ifdef GL_GLEXT_PROTOTYPES -GLAPI void APIENTRY glUploadGpuMaskNVX (GLbitfield mask); +GLAPI void APIENTRY glUploadGPUMaskNVX (GLbitfield mask); GLAPI void APIENTRY glMulticastViewportArrayvNVX (GLuint gpu, GLuint first, GLsizei count, const GLfloat *v); GLAPI void APIENTRY glMulticastViewportPositionWScaleNVX (GLuint gpu, GLuint index, GLfloat xcoeff, GLfloat ycoeff); GLAPI void APIENTRY glMulticastScissorArrayvNVX (GLuint gpu, GLuint first, GLsizei count, const GLint *v); -GLAPI GLuint APIENTRY glAsyncCopyBufferSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); -GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +GLAPI GLuint APIENTRY glAsyncCopyBufferSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *fenceValueArray, GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); +GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, const GLuint *waitSemaphoreArray, const GLuint64 *waitValueArray, GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth, GLsizei signalSemaphoreCount, const GLuint *signalSemaphoreArray, const GLuint64 *signalValueArray); #endif #endif /* GL_NVX_gpu_multicast2 */ @@ -9824,11 +9824,11 @@ GLAPI GLuint APIENTRY glAsyncCopyImageSubDataNVX (GLsizei waitSemaphoreCount, co #define GL_LGPU_SEPARATE_STORAGE_BIT_NVX 0x0800 #define GL_MAX_LGPU_GPUS_NVX 0x92BA typedef void (APIENTRYP PFNGLLGPUNAMEDBUFFERSUBDATANVXPROC) (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -typedef void (APIENTRYP PFNGLLGPUCOPYIMAGESUBDATANVXPROC) (GLuint sourceGpu, GLbitfield destinationGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); +typedef void (APIENTRYP PFNGLLGPUCOPYIMAGESUBDATANVXPROC) (GLuint sourceGPU, GLbitfield destinationGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); typedef void (APIENTRYP PFNGLLGPUINTERLOCKNVXPROC) (void); #ifdef GL_GLEXT_PROTOTYPES GLAPI void APIENTRY glLGPUNamedBufferSubDataNVX (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -GLAPI void APIENTRY glLGPUCopyImageSubDataNVX (GLuint sourceGpu, GLbitfield destinationGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); +GLAPI void APIENTRY glLGPUCopyImageSubDataNVX (GLuint sourceGPU, GLbitfield destinationGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srxY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei width, GLsizei height, GLsizei depth); GLAPI void APIENTRY glLGPUInterlockNVX (void); #endif #endif /* GL_NVX_linked_gpu_multicast */ @@ -9836,13 +9836,13 @@ GLAPI void APIENTRY glLGPUInterlockNVX (void); #ifndef GL_NVX_progress_fence #define GL_NVX_progress_fence 1 typedef GLuint (APIENTRYP PFNGLCREATEPROGRESSFENCENVXPROC) (void); -typedef void (APIENTRYP PFNGLSIGNALSEMAPHOREUI64NVXPROC) (GLuint signalGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); -typedef void (APIENTRYP PFNGLWAITSEMAPHOREUI64NVXPROC) (GLuint waitGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +typedef void (APIENTRYP PFNGLSIGNALSEMAPHOREUI64NVXPROC) (GLuint signalGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +typedef void (APIENTRYP PFNGLWAITSEMAPHOREUI64NVXPROC) (GLuint waitGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); typedef void (APIENTRYP PFNGLCLIENTWAITSEMAPHOREUI64NVXPROC) (GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); #ifdef GL_GLEXT_PROTOTYPES GLAPI GLuint APIENTRY glCreateProgressFenceNVX (void); -GLAPI void APIENTRY glSignalSemaphoreui64NVX (GLuint signalGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); -GLAPI void APIENTRY glWaitSemaphoreui64NVX (GLuint waitGpu, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +GLAPI void APIENTRY glSignalSemaphoreui64NVX (GLuint signalGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); +GLAPI void APIENTRY glWaitSemaphoreui64NVX (GLuint waitGPU, GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); GLAPI void APIENTRY glClientWaitSemaphoreui64NVX (GLsizei fenceObjectCount, const GLuint *semaphoreArray, const GLuint64 *fenceValueArray); #endif #endif /* GL_NVX_progress_fence */ @@ -10433,25 +10433,25 @@ GLAPI void APIENTRY glFramebufferTextureFaceEXT (GLenum target, GLenum attachmen #define GL_MULTICAST_PROGRAMMABLE_SAMPLE_LOCATION_NV 0x9549 typedef void (APIENTRYP PFNGLRENDERGPUMASKNVPROC) (GLbitfield mask); typedef void (APIENTRYP PFNGLMULTICASTBUFFERSUBDATANVPROC) (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -typedef void (APIENTRYP PFNGLMULTICASTCOPYBUFFERSUBDATANVPROC) (GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); -typedef void (APIENTRYP PFNGLMULTICASTCOPYIMAGESUBDATANVPROC) (GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); -typedef void (APIENTRYP PFNGLMULTICASTBLITFRAMEBUFFERNVPROC) (GLuint srcGpu, GLuint dstGpu, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); +typedef void (APIENTRYP PFNGLMULTICASTCOPYBUFFERSUBDATANVPROC) (GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); +typedef void (APIENTRYP PFNGLMULTICASTCOPYIMAGESUBDATANVPROC) (GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); +typedef void (APIENTRYP PFNGLMULTICASTBLITFRAMEBUFFERNVPROC) (GLuint srcGPU, GLuint dstGPU, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); typedef void (APIENTRYP PFNGLMULTICASTFRAMEBUFFERSAMPLELOCATIONSFVNVPROC) (GLuint gpu, GLuint framebuffer, GLuint start, GLsizei count, const GLfloat *v); typedef void (APIENTRYP PFNGLMULTICASTBARRIERNVPROC) (void); -typedef void (APIENTRYP PFNGLMULTICASTWAITSYNCNVPROC) (GLuint signalGpu, GLbitfield waitGpuMask); +typedef void (APIENTRYP PFNGLMULTICASTWAITSYNCNVPROC) (GLuint signalGPU, GLbitfield waitGPUMask); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTIVNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLint *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTUIVNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLuint *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTI64VNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLint64 *params); typedef void (APIENTRYP PFNGLMULTICASTGETQUERYOBJECTUI64VNVPROC) (GLuint gpu, GLuint id, GLenum pname, GLuint64 *params); #ifdef GL_GLEXT_PROTOTYPES -GLAPI void APIENTRY glRenderGpuMaskNV (GLbitfield mask); +GLAPI void APIENTRY glRenderGPUMaskNV (GLbitfield mask); GLAPI void APIENTRY glMulticastBufferSubDataNV (GLbitfield gpuMask, GLuint buffer, GLintptr offset, GLsizeiptr size, const void *data); -GLAPI void APIENTRY glMulticastCopyBufferSubDataNV (GLuint readGpu, GLbitfield writeGpuMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); -GLAPI void APIENTRY glMulticastCopyImageSubDataNV (GLuint srcGpu, GLbitfield dstGpuMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); -GLAPI void APIENTRY glMulticastBlitFramebufferNV (GLuint srcGpu, GLuint dstGpu, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); +GLAPI void APIENTRY glMulticastCopyBufferSubDataNV (GLuint readGPU, GLbitfield writeGPUMask, GLuint readBuffer, GLuint writeBuffer, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size); +GLAPI void APIENTRY glMulticastCopyImageSubDataNV (GLuint srcGPU, GLbitfield dstGPUMask, GLuint srcName, GLenum srcTarget, GLint srcLevel, GLint srcX, GLint srcY, GLint srcZ, GLuint dstName, GLenum dstTarget, GLint dstLevel, GLint dstX, GLint dstY, GLint dstZ, GLsizei srcWidth, GLsizei srcHeight, GLsizei srcDepth); +GLAPI void APIENTRY glMulticastBlitFramebufferNV (GLuint srcGPU, GLuint dstGPU, GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter); GLAPI void APIENTRY glMulticastFramebufferSampleLocationsfvNV (GLuint gpu, GLuint framebuffer, GLuint start, GLsizei count, const GLfloat *v); GLAPI void APIENTRY glMulticastBarrierNV (void); -GLAPI void APIENTRY glMulticastWaitSyncNV (GLuint signalGpu, GLbitfield waitGpuMask); +GLAPI void APIENTRY glMulticastWaitSyncNV (GLuint signalGPU, GLbitfield waitGPUMask); GLAPI void APIENTRY glMulticastGetQueryObjectivNV (GLuint gpu, GLuint id, GLenum pname, GLint *params); GLAPI void APIENTRY glMulticastGetQueryObjectuivNV (GLuint gpu, GLuint id, GLenum pname, GLuint *params); GLAPI void APIENTRY glMulticastGetQueryObjecti64vNV (GLuint gpu, GLuint id, GLenum pname, GLint64 *params); diff --git a/Source/ThirdParty/SDL/SDL3/SDL_pen.h b/Source/ThirdParty/SDL/SDL3/SDL_pen.h index c02c0081f..77c7bed9a 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_pen.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_pen.h @@ -22,32 +22,23 @@ /** * # CategoryPen * - * Include file for SDL pen event handling. + * SDL pen event handling. * - * This file describes operations for pressure-sensitive pen (stylus and/or - * eraser) handling, e.g., for input and drawing tablets or suitably equipped - * mobile / tablet devices. + * 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: + * To get started with pens, simply handle SDL_EVENT_PEN_* events. When a pen + * starts providing input, SDL will assign it a unique SDL_PenID, which will + * remain for the life of the process, as long as the pen stays connected. * - * - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent - * - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent - * and SDL_MouseButtonEvent whenever `which` == SDL_PEN_MOUSEID. - * - * We primarily identify pens by SDL_PenID. The implementation makes a best - * effort to relate each SDL_PenID to the same physical device during a - * session. Formerly valid SDL_PenID values remain valid even if a device - * disappears. - * - * For identifying pens across sessions, the API provides the type SDL_GUID . + * Pens may provide more than simple touch input; they might have other axes, + * such as pressure, tilt, rotation, etc. */ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include -#include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,23 +46,42 @@ extern "C" { #endif -typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */ +/** + * SDL pen instance IDs. + * + * Zero is used to signify an invalid/null device. + * + * These show up in pen events when SDL sees input from them. They remain + * consistent as long as SDL can recognize a tool to be the same pen; but if a + * pen physically leaves the area and returns, it might get a new ID. + * + * \since This datatype is available since SDL 3.0.0. + */ +typedef Uint32 SDL_PenID; -#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid SDL_PenID is valid */ - -#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) /**< Device ID for mouse events triggered by pen events */ - -#define SDL_PEN_INFO_UNKNOWN (-1) /**< Marks unknown information when querying the pen */ /** - * Pen axis indices + * Pen input flags, as reported by various pen events' `pen_state` field. * - * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and - * SDL_PenButtonEvent. The axis indices form a contiguous range of ints from 0 - * to SDL_PEN_AXIS_LAST, inclusive. All "axis[]" entries 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 entries are always "0.0f". + * \since This datatype is available since SDL 3.0.0. + */ +typedef Uint32 SDL_PenInputFlags; + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ + +/** + * Pen axis indices. + * + * These are the valid values for the `axis` field in SDL_PenAxisEvent. All + * axes are either normalised to 0..1 or report a (positive or negative) angle + * in degrees, with 0.0 representing the centre. Not all pens/backends support + * all axes: unsupported axes are always zero. * * To convert angles for tilt and rotation into vector representation, use * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example: @@ -82,200 +92,16 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio */ typedef enum SDL_PenAxis { - SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0..1.0 */ - SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ - SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0 */ - SDL_PEN_NUM_AXES, /**< Last valid axis index */ - SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */ + SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ + SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ + SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ + SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ + SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; -/* Pen flags. These share a bitmask space with SDL_BUTTON_LEFT and friends. */ -#define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */ -#define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */ -#define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */ -#define SDL_PEN_FLAG_AXIS_BIT_OFFSET 16 /* Bit for storing has-axis-0 property */ - -#define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit)) -#define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET) - -/* Pen tips */ -#define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */ -#define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */ - -/** - * Pen capabilities reported by SDL_GetPenCapabilities. - * - * \since This datatype is available since SDL 3.0.0. - */ -typedef Uint32 SDL_PenCapabilityFlags; - -#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */ -#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (SDL_GetPenCapabilities). For events (SDL_PenButtonEvent, SDL_PenMotionEvent, SDL_GetPenStatus) this flag is mutually exclusive with SDL_PEN_ERASER_MASK . */ -#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (SDL_GetPenCapabilities) or is being used as eraser (SDL_PenButtonEvent , SDL_PenMotionEvent , SDL_GetPenStatus) */ -#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */ -#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis SDL_PEN_AXIS_XTILT */ -#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis SDL_PEN_AXIS_YTILT */ -#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in SDL_PEN_AXIS_DISTANCE */ -#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis SDL_PEN_AXIS_ROTATION */ -#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis SDL_PEN_AXIS_SLIDER */ -#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK) - -/** - * Pen types - * - * Some pens identify as a particular type of drawing device (e.g., an - * airbrush or a pencil). - * - * \since This enum is available since SDL 3.0.0 - */ -typedef enum SDL_PenSubtype -{ - SDL_PEN_TYPE_UNKNOWN = 0, - SDL_PEN_TYPE_ERASER = 1, /**< Eraser */ - SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */ - SDL_PEN_TYPE_PENCIL, /**< Pencil */ - SDL_PEN_TYPE_BRUSH, /**< Brush-like device */ - SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */ - SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */ -} SDL_PenSubtype; - - -/* Function prototypes */ - -/** - * Retrieves all pens that are connected to the system. - * - * Yields an array of SDL_PenID values. These identify and track pens - * throughout a session. To track pens across sessions (program restart), use - * SDL_GUID . - * - * \param count the number of pens in the array (number of array elements - * minus 1, i.e., not counting the terminator 0). - * \returns a 0 terminated array of SDL_PenID values, or NULL on failure. The - * array must be freed with SDL_free(). On a NULL return, - * SDL_GetError() is set. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_PenID * SDLCALL SDL_GetPens(int *count); - -/** - * Retrieves the pen's current status. - * - * If the pen is detached (cf. SDL_PenConnected), this operation may return - * default values. - * - * \param instance_id the pen to query. - * \param x out-mode parameter for pen x coordinate. May be NULL. - * \param y out-mode parameter for pen y coordinate. May be NULL. - * \param axes out-mode parameter for axis information. May be null. The axes - * are in the same order as SDL_PenAxis. - * \param num_axes maximum number of axes to write to "axes". - * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK - * etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of - * SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see - * SDL_GetError()). - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes); - -/** - * Retrieves an SDL_PenID for the given SDL_GUID. - * - * \param guid a pen GUID. - * \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching - * SDL_PenID. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid); - -/** - * Retrieves the SDL_GUID for a given SDL_PenID. - * - * \param instance_id the pen to query. - * \returns the corresponding pen GUID; persistent across multiple sessions. - * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id); - -/** - * Checks whether a pen is still attached. - * - * If a pen is detached, it will not show up for SDL_GetPens(). Other - * operations will still be available but may return default values. - * - * \param instance_id a pen ID. - * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is - * attached, or SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id); - -/** - * Retrieves a human-readable description for a SDL_PenID. - * - * \param instance_id the pen to query. - * \returns a string that contains the name of the pen, intended for human - * consumption. The string might or might not be localised, depending - * on platform settings. It is not guaranteed to be unique; use - * SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer - * is managed by the SDL pen subsystem and must not be deallocated. - * The pointer remains valid until SDL is shut down. Returns NULL on - * error (cf. SDL_GetError()). - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetPenName(SDL_PenID instance_id); - -/** - * Pen capabilities, as reported by SDL_GetPenCapabilities() - * - * \since This struct is available since SDL 3.0.0. - */ -typedef struct SDL_PenCapabilityInfo -{ - float max_tilt; /**< Physical maximum tilt angle, for XTILT and YTILT, or SDL_PEN_INFO_UNKNOWN . Pens cannot typically tilt all the way to 90 degrees, so this value is usually less than 90.0. */ - Uint32 wacom_id; /**< For Wacom devices: wacom tool type ID, otherwise 0 (useful e.g. with libwacom) */ - Sint8 num_buttons; /**< Number of pen buttons (not counting the pen tip), or SDL_PEN_INFO_UNKNOWN */ -} SDL_PenCapabilityInfo; - -/** - * Retrieves capability flags for a given SDL_PenID. - * - * \param instance_id the pen to query. - * \param capabilities detail information about pen capabilities, such as the - * number of buttons. - * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_PenCapabilityFlags SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities); - -/** - * Retrieves the pen type for a given SDL_PenID. - * - * \param instance_id the pen to query. - * \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error. - * Note that the pen type does not dictate whether the pen tip is - * SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen - * is being used for drawing or in eraser mode, check either the pen - * tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK in the - * pen state. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id); - /* Ends C function definitions when using C++ */ #ifdef __cplusplus } @@ -283,4 +109,3 @@ extern SDL_DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id) #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_pixels.h b/Source/ThirdParty/SDL/SDL3/SDL_pixels.h index 851d5950f..820e29957 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_pixels.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_pixels.h @@ -47,6 +47,15 @@ extern "C" { */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * @@ -56,7 +65,20 @@ extern "C" { */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +97,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +109,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +127,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +143,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -351,30 +389,30 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ -} SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif +} SDL_PixelFormat; /** * Pixels are a representation of a color in a particular color space. @@ -631,7 +669,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +677,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -742,8 +775,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -751,7 +784,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC int SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -819,15 +852,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -874,6 +907,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * * \since This function is available since SDL 3.0.0. * + * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB * \sa SDL_MapRGBA * \sa SDL_MapSurfaceRGB @@ -912,6 +946,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * * \since This function is available since SDL 3.0.0. * + * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA * \sa SDL_MapRGB * \sa SDL_MapSurfaceRGBA @@ -939,6 +974,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * * \since This function is available since SDL 3.0.0. * + * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA * \sa SDL_MapRGB * \sa SDL_MapRGBA @@ -970,6 +1006,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * * \since This function is available since SDL 3.0.0. * + * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB * \sa SDL_MapRGB * \sa SDL_MapRGBA diff --git a/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h b/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h index e7f91cf94..4f878e3b2 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_platform_defines.h @@ -29,180 +29,451 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * 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.0.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif + #ifdef __NGAGE__ + +/** + * A preprocessor macro that is only defined if compiling for Nokia N-Gage. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_NGAGE 1 #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * 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.0.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * 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.0.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * 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.0.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ #if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H -#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.0.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * 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.0.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.0.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_process.h b/Source/ThirdParty/SDL/SDL3/SDL_process.h new file mode 100644 index 000000000..1dfac1917 --- /dev/null +++ b/Source/ThirdParty/SDL/SDL3/SDL_process.h @@ -0,0 +1,417 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2024 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERIT, 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.0.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, 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 go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * so if you may need to call SDL_GetOutputStream() 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.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * \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.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_properties.h b/Source/ThirdParty/SDL/SDL3/SDL_properties.h index b3e061adc..393d473a1 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_properties.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_properties.h @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,8 +138,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro * thread. * * \param props the properties to lock. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -147,7 +147,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -204,8 +204,8 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -215,7 +215,7 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,8 +223,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -238,7 +238,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Properties * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,8 +249,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, c * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -258,7 +258,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, c * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,8 +266,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -275,7 +275,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,8 +283,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -292,7 +292,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,8 +300,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -309,14 +309,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * @@ -324,7 +324,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, c * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -463,21 +463,21 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_rect.h b/Source/ThirdParty/SDL/SDL3/SDL_rect.h index 058330098..d0f0bbcba 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_rect.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_rect.h @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,26 +194,26 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * 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 SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * @@ -221,27 +221,24 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A, - const SDL_Rect * B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * 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 SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A, - const SDL_Rect * B, - SDL_Rect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -250,14 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A, - const SDL_Rect * B, - SDL_Rect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -271,15 +266,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A, * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \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.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * points, - int count, - const SDL_Rect * clip, - SDL_Rect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -295,14 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect * - rect, int *X1, - int *Y1, int *X2, - int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -322,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -346,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \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.0.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -374,7 +363,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * @@ -382,14 +371,14 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -409,7 +398,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * @@ -417,7 +406,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -425,37 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * 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 SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect * A, - const SDL_FRect * B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * 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 SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect * A, - const SDL_FRect * B, - SDL_FRect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -464,14 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A, - const SDL_FRect * B, - SDL_FRect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -486,15 +470,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A, * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \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.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint * points, - int count, - const SDL_FRect * clip, - SDL_FRect * result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -511,14 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect * - rect, float *X1, - float *Y1, float *X2, - float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_render.h b/Source/ThirdParty/SDL/SDL3/SDL_render.h index c02b71e9b..820fa5a43 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_render.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_render.h @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * 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 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -115,11 +118,28 @@ typedef enum SDL_RendererLogicalPresentation */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -133,8 +153,9 @@ typedef struct SDL_Texture SDL_Texture; * * There may be none if SDL was compiled without render support. * - * \returns a number >= 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * @@ -159,6 +180,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \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.0.0. * * \sa SDL_GetNumRenderDrivers @@ -175,15 +198,17 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. @@ -204,6 +229,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(const char *title, i * \returns a valid rendering context or NULL if there was an error; 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.0.0. * * \sa SDL_CreateRendererWithProperties @@ -256,6 +283,8 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; 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.0.0. * * \sa SDL_CreateProperties @@ -266,17 +295,17 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_PropertiesID props); -#define SDL_PROP_RENDERER_CREATE_NAME_STRING "name" -#define SDL_PROP_RENDERER_CREATE_WINDOW_POINTER "window" -#define SDL_PROP_RENDERER_CREATE_SURFACE_POINTER "surface" -#define SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER "output_colorspace" -#define SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER "present_vsync" -#define SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER "vulkan.instance" -#define SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER "vulkan.surface" -#define SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER "vulkan.physical_device" -#define SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER "vulkan.device" -#define SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "vulkan.graphics_queue_family_index" -#define SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "vulkan.present_queue_family_index" +#define SDL_PROP_RENDERER_CREATE_NAME_STRING "SDL.renderer.create.name" +#define SDL_PROP_RENDERER_CREATE_WINDOW_POINTER "SDL.renderer.create.window" +#define SDL_PROP_RENDERER_CREATE_SURFACE_POINTER "SDL.renderer.create.surface" +#define SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.create.output_colorspace" +#define SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER "SDL.renderer.create.present_vsync" +#define SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER "SDL.renderer.create.vulkan.instance" +#define SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER "SDL.renderer.create.vulkan.surface" +#define SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.create.vulkan.physical_device" +#define SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER "SDL.renderer.create.vulkan.device" +#define SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.graphics_queue_family_index" +#define SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.create.vulkan.present_queue_family_index" /** * Create a 2D software rendering context for a surface. @@ -291,6 +320,8 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; 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.0.0. * * \sa SDL_DestroyRenderer @@ -304,6 +335,8 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \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.0.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -315,6 +348,8 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \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.0.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -326,6 +361,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \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.0.0. * * \sa SDL_CreateRenderer @@ -408,6 +445,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * \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.0.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -445,14 +484,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -465,18 +506,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. @@ -486,6 +531,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *ren * was active, the format was unsupported, or the width or height * were out of range; 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.0.0. * * \sa SDL_CreateTextureFromSurface @@ -514,6 +561,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL 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.0.0. * * \sa SDL_CreateTexture @@ -622,6 +671,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * was active, the format was unsupported, or the width or height * were out of range; 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.0.0. * * \sa SDL_CreateProperties @@ -633,29 +684,29 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende */ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props); -#define SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER "colorspace" -#define SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER "format" -#define SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER "access" -#define SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER "width" -#define SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER "height" -#define SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT "SDR_white_point" -#define SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT "HDR_headroom" -#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "d3d11.texture" -#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "d3d11.texture_u" -#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "d3d11.texture_v" -#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "d3d12.texture" -#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "d3d12.texture_u" -#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "d3d12.texture_v" -#define SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER "metal.pixelbuffer" -#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "opengl.texture" -#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "opengl.texture_uv" -#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "opengl.texture_u" -#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "opengl.texture_v" -#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "opengles2.texture" -#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "opengles2.texture_uv" -#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "opengles2.texture_u" -#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "opengles2.texture_v" -#define SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER "vulkan.texture" +#define SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER "SDL.texture.create.colorspace" +#define SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER "SDL.texture.create.format" +#define SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER "SDL.texture.create.access" +#define SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER "SDL.texture.create.width" +#define SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER "SDL.texture.create.height" +#define SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT "SDL.texture.create.SDR_white_point" +#define SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT "SDL.texture.create.HDR_headroom" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "SDL.texture.create.d3d11.texture" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "SDL.texture.create.d3d11.texture_u" +#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "SDL.texture.create.d3d11.texture_v" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "SDL.texture.create.d3d12.texture" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "SDL.texture.create.d3d12.texture_u" +#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "SDL.texture.create.d3d12.texture_v" +#define SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER "SDL.texture.create.metal.pixelbuffer" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "SDL.texture.create.opengl.texture" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.create.opengl.texture_uv" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.create.opengl.texture_u" +#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.create.opengl.texture_v" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.create.opengles2.texture" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.create.opengles2.texture_uv" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.create.opengles2.texture_u" +#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.create.opengles2.texture_v" +#define SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER "SDL.texture.create.vulkan.texture" /** * Get the properties associated with a texture. @@ -750,6 +801,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * \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.0.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -802,12 +855,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,15 +873,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float * * * `srcC = srcC * (color / 255)` * - * Color modulation is not always supported by the renderer; it will return -1 - * if color modulation is not supported. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -834,7 +891,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float * * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,15 +903,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uin * * `srcC = srcC * color` * - * Color modulation is not always supported by the renderer; it will return -1 - * if color modulation is not supported. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -862,7 +921,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uin * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -872,8 +931,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * @@ -881,7 +942,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -890,8 +951,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uin * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * @@ -899,7 +962,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uin * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,13 +972,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture * * `srcA = srcA * (alpha / 255)` * - * Alpha modulation is not always supported by the renderer; it will return -1 - * if alpha modulation is not supported. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -923,7 +988,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,13 +998,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uin * * `srcA = srcA * alpha` * - * Alpha modulation is not always supported by the renderer; it will return -1 - * if alpha modulation is not supported. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -947,15 +1014,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uin * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -963,15 +1032,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -979,38 +1050,42 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uin * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1021,28 +1096,32 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SD * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1064,8 +1143,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SD * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * @@ -1074,7 +1155,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SD * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1096,15 +1177,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SD * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1126,15 +1209,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1158,16 +1243,18 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns 0 on success or a negative error code if the texture is not valid - * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \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 You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1195,17 +1282,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture, * NULL, the entire texture will be locked. * \param surface this is filled in with an SDL surface representing the * locked area. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, - const SDL_Rect *rect, - SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1220,6 +1307,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, * * \param texture a texture locked by SDL_LockTexture(). * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_LockTexture @@ -1237,14 +1326,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1255,6 +1346,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_ * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderTarget @@ -1264,13 +1357,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window 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. * * 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 output window. + * resolution of the output window; 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. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1279,9 +1382,10 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -1289,7 +1393,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1300,16 +1404,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *r * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param mode the presentation mode used. + * \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.0.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1322,36 +1427,54 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *r * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1359,19 +1482,29 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *re * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * @@ -1379,45 +1512,57 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *rend * * \param renderer the rendering context. * \param event the event to modify. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1427,15 +1572,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SD * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1450,12 +1597,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1463,15 +1612,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SD * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1479,29 +1630,33 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, co * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; 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.0.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1517,14 +1672,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1532,14 +1689,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1554,15 +1713,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1577,15 +1738,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, U * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1599,15 +1762,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1621,15 +1786,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, U * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1644,28 +1811,32 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *render * * \param renderer the rendering context. * \param scale the color scale value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1674,28 +1845,32 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1706,14 +1881,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *rendere * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1721,14 +1898,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1736,14 +1915,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1753,14 +1934,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const S * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1769,14 +1952,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1784,14 +1969,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1800,14 +1987,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1816,14 +2005,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1832,14 +2023,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1851,15 +2044,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1878,17 +2073,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Te * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1906,14 +2103,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1938,14 +2137,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, S * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1960,14 +2161,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, S * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1990,14 +2193,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2020,6 +2225,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * \returns a new SDL_Surface on success or NULL 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.0.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2044,16 +2251,18 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * 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, 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. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * @@ -2070,7 +2279,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC int SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2080,6 +2289,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateTexture @@ -2095,6 +2306,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateRenderer @@ -2125,12 +2338,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2142,6 +2357,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderMetalCommandEncoder @@ -2163,6 +2380,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * + * \threadsafety You may only call this function from the main thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderMetalLayer @@ -2190,15 +2409,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2214,14 +2433,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *rend * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2232,14 +2453,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int v * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC int SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_revision.h b/Source/ThirdParty/SDL/SDL3/SDL_revision.h index 49503e19e..38a6add60 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_revision.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_revision.h @@ -31,9 +31,9 @@ /* #undef SDL_VENDOR_INFO */ #ifdef SDL_VENDOR_INFO -#define SDL_REVISION "SDL-627cb8acd (" SDL_VENDOR_INFO ")" +#define SDL_REVISION "SDL-preview-3.1.3 (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "SDL-627cb8acd" +#define SDL_REVISION "SDL-preview-3.1.3" #endif #endif /* SDL_revision_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_scancode.h b/Source/ThirdParty/SDL/SDL3/SDL_scancode.h index ccf8bb5f7..16fb2a828 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_scancode.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_scancode.h @@ -417,8 +417,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h index 2d4aa468d..2ad2fc029 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_sensor.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_sensor.h @@ -23,6 +23,10 @@ * # CategorySensor * * SDL sensor management. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -40,23 +44,13 @@ extern "C" { /* *INDENT-ON* */ #endif -/** - * SDL_sensor.h - * - * 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. - */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** * This is a unique ID for a sensor for the time it is connected to the * system, and is never reused for the lifetime of the application. * - * The ID value starts at 1 and increments from there. The value 0 is an - * invalid ID. + * The value 0 is an invalid ID. * * \since This datatype is available since SDL 3.0.0. */ @@ -278,12 +272,12 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). diff --git a/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h b/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h index 14e075099..c484c3712 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_stdinc.h @@ -23,8 +23,10 @@ * # CategoryStdinc * * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * subset of the C runtime APIs, but with an `SDL_` prefix. For most common + * use cases, these should behave the same way as their C runtime equivalents, + * but they may differ in how or whether they handle certain edge cases. When + * in doubt, consult the documentation for details. */ #ifndef SDL_stdinc_h_ @@ -32,14 +34,29 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -77,6 +94,25 @@ void *alloca(size_t); # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#if defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] +#endif + /** * Check if the compiler supports a given builtin. * Supported by virtually all clang versions and recent gcc. Use this @@ -119,7 +155,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -128,9 +233,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define 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.0.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -184,34 +303,6 @@ void *alloca(size_t); */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE 0 - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE 1 - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef int SDL_bool; - /** * A signed 8-bit integer type. * @@ -330,10 +421,10 @@ typedef Sint64 SDL_Time; /* @} *//* Floating-point constants */ /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" #elif defined(PRIs64) #define SDL_PRIs64 PRIs64 @@ -344,7 +435,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 @@ -355,7 +446,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -366,7 +457,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -404,6 +495,25 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ #ifdef SDL_DISABLE_ANALYZE_MACROS @@ -420,7 +530,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -450,46 +560,37 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -519,6 +620,51 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + #ifndef SDL_DISABLE_ALLOCA #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) @@ -527,14 +673,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \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.0.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \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.0.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \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.0.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -595,8 +911,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations @@ -607,26 +923,26 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, - SDL_calloc_func calloc_func, - SDL_realloc_func realloc_func, - SDL_free_func free_func); +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, + SDL_calloc_func calloc_func, + SDL_realloc_func realloc_func, + SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * 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. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * @@ -642,7 +958,9 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * 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. * @@ -663,16 +981,463 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.0.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.0.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->n < A->n) { + * 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. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->n < A->n) { + * 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. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); @@ -920,7 +1685,26 @@ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,6 +1719,23 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory. + * + * 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.0.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -964,8 +1765,63 @@ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * 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.0.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns The length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); @@ -1092,13 +1948,121 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns The parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * 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.0.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns The number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns The length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); @@ -1158,15 +2122,215 @@ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, 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.0.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns The parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns The parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns The parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +/** + * 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.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns The parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +/** + * 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.0.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1287,6 +2451,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * @@ -1378,10 +2560,10 @@ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); @@ -2899,14 +4081,78 @@ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); #define SDL_ICONV_EILSEQ (size_t)-3 #define SDL_ICONV_EINVAL (size_t)-4 -/* SDL_iconv_* are now always real symbols/types, not macros or inlined. */ typedef struct SDL_iconv_data_t *SDL_iconv_t; + +/** + * This function allocates a context for the specified character set + * conversion. + * + * \param tocode The target character encoding, must not be NULL. + * \param fromcode The source character encoding, must not be NULL. + * \returns a handle that must be freed with SDL_iconv_close, or + * SDL_ICONV_ERROR on failure. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, const char *fromcode); + +/** + * This function frees a context used for character set conversion. + * + * \param cd The character set conversion handle. + * \returns 0 on success, or -1 on failure. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_iconv + * \sa SDL_iconv_open + * \sa SDL_iconv_string + */ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); + +/** + * This function converts text between encodings, reading from and writing to + * a buffer. + * + * It returns the number of succesful conversions. + * + * \param cd The character set conversion context, created in + * SDL_iconv_open(). + * \param inbuf Address of variable that points to the first character of the + * input sequence. + * \param inbytesleft The number of bytes in the input buffer. + * \param outbuf Address of variable that points to the output buffer. + * \param outbytesleft The number of bytes in the output buffer. + * \returns the number of conversions on success, else SDL_ICONV_E2BIG is + * returned when the output buffer is too small, or SDL_ICONV_EILSEQ + * is returned when an invalid input sequence is encountered, or + * SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte + * sequence. On error, this is the location of the problematic + * input sequence. On success, this is the end of the input + * sequence. - inbytesleft will be set to the number of bytes left + * to convert, which will be 0 on success. - outbuf will point to + * the location where to store the next output byte. - outbytesleft + * will be set to the number of bytes left in the output buffer. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv_string + */ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, - size_t * inbytesleft, char **outbuf, - size_t * outbytesleft); + size_t *inbytesleft, char **outbuf, + size_t *outbytesleft); /** * Helper function to convert a string's encoding in one call. @@ -2928,6 +4174,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \returns a new string, converted to the new encoding, or NULL on error. * * \since This function is available since SDL 3.0.0. + * + * \sa SDL_iconv_open + * \sa SDL_iconv_close + * \sa SDL_iconv */ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *fromcode, @@ -3001,6 +4251,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3010,29 +4261,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * 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 + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \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.0.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3040,13 +4289,11 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif @@ -3059,41 +4306,55 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \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.0.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.0.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Source/ThirdParty/SDL/SDL3/SDL_storage.h b/Source/ThirdParty/SDL/SDL3/SDL_storage.h index 7fc58a887..9edbcf8e4 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_storage.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_storage.h @@ -52,44 +52,61 @@ extern "C" { * 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.0.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - int (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - int (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - int (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - int (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - int (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - int (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - int (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - int (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - int (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -176,8 +193,12 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * 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. * @@ -186,6 +207,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,10 +218,10 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns 0 if the container was freed with no errors, a negative value - * 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. + * \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.0.0. * @@ -208,21 +230,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * 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. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,15 +252,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \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 0 if the file could be queried or a negative error code on - * failure; call SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided @@ -248,8 +270,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con * \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 0 if the file was read or a negative error code on failure; call - * SDL_GetError() for more information. + * \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.0.0. * @@ -257,7 +279,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,8 +288,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const * \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 0 if the file was written or a negative error code on failure; - * call SDL_GetError() for more information. + * \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.0.0. * @@ -275,21 +297,21 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. @@ -298,32 +320,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, * callback, called once for each directory entry, until all results have been * provided or the callback returns <= 0. * + * This will return false if there was a system problem in general, or if a + * callback returns -1. A successful return means a callback returned 1 to + * halt enumeration, or all directory entries were enumerated. + * * \param storage a storage container. * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +357,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, cons * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +372,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, cons * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +388,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const * \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 0 on success or a negative error code if the file doesn't exist, - * or another failure; call SDL_GetError() for more information. + * \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.0.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC int SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_surface.h b/Source/ThirdParty/SDL/SDL3/SDL_surface.h index 57745ac0f..2a758a6d9 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_surface.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_surface.h @@ -71,8 +71,7 @@ typedef Uint32 SDL_SurfaceFlags; typedef enum SDL_ScaleMode { SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */ - SDL_SCALEMODE_LINEAR, /**< linear filtering */ - SDL_SCALEMODE_BEST /**< anisotropic filtering */ + SDL_SCALEMODE_LINEAR /**< linear filtering */ } SDL_ScaleMode; /** @@ -87,8 +86,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -106,25 +104,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * alignment, and have undefined contents. * * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. * + * The pixels of the new surface are initialized to zero. + * * \param width the width of the surface. * \param height the height of the surface. * \param format the SDL_PixelFormat for the new surface's pixel format. @@ -222,14 +227,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * \param surface the SDL_Surface structure to update. * \param colorspace an SDL_ColorSpace value describing the surface * colorspace. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -283,15 +288,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -320,8 +325,8 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -329,14 +334,13 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC int SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or true otherwise. * * \since This function is available since SDL 3.0.0. * @@ -344,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surfac * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -400,15 +404,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. @@ -428,8 +432,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \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. * @@ -439,7 +443,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -470,17 +474,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -493,15 +497,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStrea * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -510,10 +514,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. * @@ -521,21 +524,21 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -548,11 +551,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -560,22 +562,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -583,19 +585,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -610,15 +612,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uin * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -628,15 +630,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uin * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -648,30 +650,30 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uin * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -682,28 +684,28 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uin * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -717,14 +719,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SD * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -736,26 +738,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -858,14 +860,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns false on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -887,14 +889,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pix * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns false on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -909,14 +911,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int he * \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 SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -924,14 +926,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_ * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -946,12 +948,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -969,14 +971,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -994,14 +996,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_ * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** * Performs a fast blit from the source surface to the destination surface. @@ -1065,8 +1067,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1076,7 +1078,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1090,8 +1092,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1101,7 +1103,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1115,8 +1117,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1126,7 +1128,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1141,8 +1143,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1152,7 +1154,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1167,8 +1169,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1178,7 +1180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1197,8 +1199,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1208,7 +1210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1234,8 +1236,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface @@ -1245,7 +1247,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1328,12 +1330,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1352,12 +1354,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1375,12 +1377,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1395,12 +1397,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_system.h b/Source/ThirdParty/SDL/SDL3/SDL_system.h index 9e79e7940..88e318ddf 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_system.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_system.h @@ -31,7 +31,6 @@ #include #include #include -#include #include #include @@ -44,16 +43,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * 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. @@ -61,7 +59,7 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \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. @@ -71,14 +69,13 @@ typedef struct tagMSG MSG; * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * 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`. @@ -90,7 +87,7 @@ typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -101,17 +98,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * 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 a negative error code on - * failure; call SDL_GetError() for more information. + * \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.0.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,28 +115,28 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * 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`. @@ -162,12 +155,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +171,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -240,27 +233,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC int SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -353,32 +346,23 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. @@ -479,7 +463,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -503,7 +487,7 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * \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 zero if the request was submitted, -1 if there was an error + * \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. * @@ -511,7 +495,7 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +516,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_RequestAndroidPermission(const char *permiss * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +532,38 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowAndroidToast(const char *message, int du * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.0.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -794,12 +705,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +720,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQue * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns 0 if success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_assert.h b/Source/ThirdParty/SDL/SDL3/SDL_test_assert.h index 98d8680c2..4d857b2ab 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_assert.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_assert.h @@ -34,6 +34,8 @@ #ifndef SDL_test_assert_h_ #define SDL_test_assert_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -52,7 +54,7 @@ extern "C" { * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertDescription Message to log with the assert describing it. */ -void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); +void SDLCALL SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); /* * Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. @@ -62,32 +64,31 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as * * \returns the assertCondition so it can be used to externally to break execution flow if desired. */ -int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); +int SDLCALL SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); /* * Explicitly pass without checking an assertion condition. Updates assertion counter. * * \param assertDescription Message to log with the assert describing it. */ -void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); /* * Resets the assert summary counters to zero. */ -void SDLTest_ResetAssertSummary(void); +void SDLCALL SDLTest_ResetAssertSummary(void); /* * Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. */ -void SDLTest_LogAssertSummary(void); - +void SDLCALL SDLTest_LogAssertSummary(void); /* * Converts the current assert summary state to a test result. * * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT */ -int SDLTest_AssertSummaryToTestResult(void); +int SDLCALL SDLTest_AssertSummaryToTestResult(void); #ifdef __cplusplus } diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h index a162a3de5..aeffeb93b 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_common.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_common.h @@ -53,6 +53,27 @@ typedef Uint32 SDLTest_VerboseFlags; #define VERBOSE_AUDIO 0x00000010 #define VERBOSE_MOTION 0x00000020 +/* !< Function pointer parsing one argument at argv[index], returning the number of parsed arguments, + * or a negative value when the argument is invalid */ +typedef int (SDLCALL *SDLTest_ParseArgumentsFp)(void *data, char **argv, int index); + +/* !< Finalize the argument parser. */ +typedef void (SDLCALL *SDLTest_FinalizeArgumentParserFp)(void *arg); + +typedef struct SDLTest_ArgumentParser +{ + /* !< Parse an argument. */ + SDLTest_ParseArgumentsFp parse_arguments; + /* !< Finalize this argument parser. Called once before parsing the first argument. */ + SDLTest_FinalizeArgumentParserFp finalize; + /* !< Null-terminated array of arguments. Printed when running with --help. */ + const char **usage; + /* !< User data, passed to all callbacks. */ + void *data; + /* !< Next argument parser. */ + struct SDLTest_ArgumentParser *next; +} SDLTest_ArgumentParser; + typedef struct { /* SDL init flags */ @@ -67,7 +88,7 @@ typedef struct const char *window_title; const char *window_icon; SDL_WindowFlags window_flags; - SDL_bool flash_on_focus_loss; + bool flash_on_focus_loss; int window_x; int window_y; int window_w; @@ -80,22 +101,22 @@ typedef struct float window_max_aspect; int logical_w; int logical_h; - SDL_bool auto_scale_content; + bool auto_scale_content; SDL_RendererLogicalPresentation logical_presentation; - SDL_ScaleMode logical_scale_mode; float scale; int depth; float refresh_rate; - SDL_bool fill_usable_bounds; - SDL_bool fullscreen_exclusive; + bool fill_usable_bounds; + bool fullscreen_exclusive; SDL_DisplayMode fullscreen_mode; int num_windows; SDL_Window **windows; + const char *gpudriver; /* Renderer info */ const char *renderdriver; int render_vsync; - SDL_bool skip_renderer; + bool skip_renderer; SDL_Renderer **renderers; SDL_Texture **targets; @@ -131,8 +152,14 @@ typedef struct /* Mouse info */ SDL_Rect confine; - SDL_bool hide_cursor; + bool hide_cursor; + /* Options info */ + SDLTest_ArgumentParser common_argparser; + SDLTest_ArgumentParser video_argparser; + SDLTest_ArgumentParser audio_argparser; + + SDLTest_ArgumentParser *argparser; } SDLTest_CommonState; #include @@ -151,7 +178,7 @@ extern "C" { * * \returns a newly allocated common state object. */ -SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags); +SDLTest_CommonState *SDLCALL SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags); /** * Free the common state object. @@ -160,7 +187,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags) * * \param state The common state object to destroy */ -void SDLTest_CommonDestroyState(SDLTest_CommonState *state); +void SDLCALL SDLTest_CommonDestroyState(SDLTest_CommonState *state); /** * Process one common argument. @@ -170,7 +197,7 @@ void SDLTest_CommonDestroyState(SDLTest_CommonState *state); * * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error. */ -int SDLTest_CommonArg(SDLTest_CommonState *state, int index); +int SDLCALL SDLTest_CommonArg(SDLTest_CommonState *state, int index); /** @@ -185,16 +212,16 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index); * \param argv0 argv[0], as passed to main/SDL_main. * \param options an array of strings for application specific options. The last element of the array should be NULL. */ -void SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options); +void SDLCALL SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options); /** * Open test window. * * \param state The common state describing the test window to create. * - * \returns SDL_TRUE if initialization succeeded, false otherwise + * \returns true if initialization succeeded, false otherwise */ -SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state); +bool SDLCALL SDLTest_CommonInit(SDLTest_CommonState *state); /** * Easy argument handling when test app doesn't need any custom args. @@ -203,9 +230,9 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state); * \param argc argc, as supplied to SDL_main * \param argv argv, as supplied to SDL_main * - * \returns SDL_FALSE if app should quit, true otherwise. + * \returns false if app should quit, true otherwise. */ -SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, const int argc, char **argv); +bool SDLCALL SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv); /** * Print the details of an event. @@ -214,7 +241,7 @@ SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, const int argc, c * * \param event The event to print. */ -void SDLTest_PrintEvent(const SDL_Event *event); +void SDLCALL SDLTest_PrintEvent(const SDL_Event *event); /** * Common event handler for test windows if you use a standard SDL_main. @@ -223,7 +250,7 @@ void SDLTest_PrintEvent(const SDL_Event *event); * \param event The event to handle. * \param done Flag indicating we are done. */ -void SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done); +void SDLCALL SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done); /** * Common event handler for test windows if you use SDL_AppEvent. @@ -234,7 +261,7 @@ void SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done * \param event The event to handle. * \returns Value suitable for returning from SDL_AppEvent(). */ -int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event); +SDL_AppResult SDLCALL SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event); /** * Close test window. @@ -242,7 +269,7 @@ int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event * \param state The common state used to create test window. * */ -void SDLTest_CommonQuit(SDLTest_CommonState *state); +void SDLCALL SDLTest_CommonQuit(SDLTest_CommonState *state); /** * Draws various window information (position, size, etc.) to the renderer. @@ -252,7 +279,7 @@ void SDLTest_CommonQuit(SDLTest_CommonState *state); * \param usedHeight Returns the height used, so the caller can draw more below. * */ -void SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight); +void SDLCALL SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h b/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h index 2aa84e00a..a7e18e3c7 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_compare.h @@ -53,7 +53,7 @@ extern "C" { * * \returns 0 if comparison succeeded, >0 (=number of pixels for which the comparison failed) if comparison failed, -1 if any of the surfaces were NULL, -2 if the surface sizes differ. */ -int SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, int allowable_error); +int SDLCALL SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, int allowable_error); /** * Compares 2 memory blocks for equality @@ -67,7 +67,7 @@ int SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, * * \since This function is available since SDL 3.0.0. */ -extern int SDLTest_CompareMemory(const void *actual, size_t size_actual, const void *reference, size_t size_reference); +int SDLCALL SDLTest_CompareMemory(const void *actual, size_t size_actual, const void *reference, size_t size_reference); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_crc32.h b/Source/ThirdParty/SDL/SDL3/SDL_test_crc32.h index e6316bcf5..62ece2afa 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_crc32.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_crc32.h @@ -34,13 +34,14 @@ #ifndef SDL_test_crc32_h_ #define SDL_test_crc32_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* ------------ Definitions --------- */ /* Definition shared by all CRC routines */ @@ -74,11 +75,11 @@ extern "C" { * * \param crcContext pointer to context variable * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ - int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext); - +bool SDLCALL SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext); /* * calculate a crc32 from a data block @@ -88,28 +89,28 @@ extern "C" { * \param inLen length of input buffer * \param crc32 pointer to Uint32 to store the final CRC into * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ -int SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); /* Same routine broken down into three steps */ -int SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); -int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); -int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); - +bool SDLCALL SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); +bool SDLCALL SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); /* * clean up CRC context * * \param crcContext pointer to context variable * - * \returns 0 for OK, -1 on error + * \returns true on success or false on failure; call SDL_GetError() + * for more information. * */ -int SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext); - +bool SDLCALL SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_font.h b/Source/ThirdParty/SDL/SDL3/SDL_test_font.h index 867205b86..99308abbf 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_font.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_font.h @@ -30,6 +30,10 @@ #ifndef SDL_test_font_h_ #define SDL_test_font_h_ +#include +#include +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -50,9 +54,9 @@ extern int FONT_CHARACTER_SIZE; * \param y The Y coordinate of the upper left corner of the character. * \param c The character to draw. * - * \returns 0 on success, -1 on failure. + * \returns true on success, false on failure. */ -int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); +bool SDLCALL SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); /* * Draw a UTF-8 string in the currently set font. @@ -64,9 +68,9 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); * \param y The Y coordinate of the upper left corner of the string. * \param s The string to draw. * - * \returns 0 on success, -1 on failure. + * \returns true on success, false on failure. */ -int SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s); +bool SDLCALL SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s); /* * Data used for multi-line text output @@ -91,7 +95,7 @@ typedef struct SDLTest_TextWindow * * \since This function is available since SDL 3.0.0. */ -SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h); +SDLTest_TextWindow * SDLCALL SDLTest_TextWindowCreate(float x, float y, float w, float h); /* * Display a multi-line text output window @@ -103,7 +107,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h) * * \since This function is available since SDL 3.0.0. */ -void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); +void SDLCALL SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); /* * Add text to a multi-line text output window @@ -118,7 +122,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render * * \since This function is available since SDL 3.0.0. */ -void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); +void SDLCALL SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); /* * Add text to a multi-line text output window @@ -133,7 +137,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST * * \since This function is available since SDL 3.0.0. */ -void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); +void SDLCALL SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); /* * Clear the text in a multi-line text output window @@ -142,7 +146,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char * * \since This function is available since SDL 3.0.0. */ -void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); +void SDLCALL SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); /* * Free the storage associated with a multi-line text output window @@ -151,12 +155,12 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); * * \since This function is available since SDL 3.0.0. */ -void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); +void SDLCALL SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); /* * Cleanup textures used by font drawing functions. */ -void SDLTest_CleanupTextDrawing(void); +void SDLCALL SDLTest_CleanupTextDrawing(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_fuzzer.h b/Source/ThirdParty/SDL/SDL3/SDL_test_fuzzer.h index 89606ef3b..4fdfd4989 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_fuzzer.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_fuzzer.h @@ -34,18 +34,18 @@ #ifndef SDL_test_fuzzer_h_ #define SDL_test_fuzzer_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* Based on GSOC code by Markus Kauppila */ - /** * Note: The fuzzer implementation uses a static instance of random context * internally which makes it thread-UNsafe. @@ -57,53 +57,49 @@ extern "C" { * \param execKey Execution "Key" that initializes the random number generator uniquely for the test. * */ -void SDLTest_FuzzerInit(Uint64 execKey); - +void SDLCALL SDLTest_FuzzerInit(Uint64 execKey); /** * Returns a random Uint8 * * \returns a generated integer */ -Uint8 SDLTest_RandomUint8(void); +Uint8 SDLCALL SDLTest_RandomUint8(void); /** * Returns a random Sint8 * * \returns a generated signed integer */ -Sint8 SDLTest_RandomSint8(void); - +Sint8 SDLCALL SDLTest_RandomSint8(void); /** * Returns a random Uint16 * * \returns a generated integer */ -Uint16 SDLTest_RandomUint16(void); +Uint16 SDLCALL SDLTest_RandomUint16(void); /** * Returns a random Sint16 * * \returns a generated signed integer */ -Sint16 SDLTest_RandomSint16(void); - +Sint16 SDLCALL SDLTest_RandomSint16(void); /** * Returns a random integer * * \returns a generated integer */ -Sint32 SDLTest_RandomSint32(void); - +Sint32 SDLCALL SDLTest_RandomSint32(void); /** * Returns a random positive integer * * \returns a generated integer */ -Uint32 SDLTest_RandomUint32(void); +Uint32 SDLCALL SDLTest_RandomUint32(void); /** * Returns random Uint64. @@ -112,35 +108,34 @@ Uint32 SDLTest_RandomUint32(void); */ Uint64 SDLTest_RandomUint64(void); - /** * Returns random Sint64. * * \returns a generated signed integer */ -Sint64 SDLTest_RandomSint64(void); +Sint64 SDLCALL SDLTest_RandomSint64(void); /** * \returns a random float in range [0.0 - 1.0] */ -float SDLTest_RandomUnitFloat(void); +float SDLCALL SDLTest_RandomUnitFloat(void); /** * \returns a random double in range [0.0 - 1.0] */ -double SDLTest_RandomUnitDouble(void); +double SDLCALL SDLTest_RandomUnitDouble(void); /** * \returns a random float. * */ -float SDLTest_RandomFloat(void); +float SDLCALL SDLTest_RandomFloat(void); /** * \returns a random double. * */ -double SDLTest_RandomDouble(void); +double SDLCALL SDLTest_RandomDouble(void); /** * Returns a random boundary value for Uint8 within the given boundaries. @@ -150,10 +145,10 @@ double SDLTest_RandomDouble(void); * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint8BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint8BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint8BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint8BoundaryValue(0, 255, SDL_FALSE) returns 0 (error set) + * RandomUint8BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint8BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint8BoundaryValue(0, 99, false) returns 100 + * RandomUint8BoundaryValue(0, 255, false) returns 0 (error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -161,7 +156,7 @@ double SDLTest_RandomDouble(void); * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain); +Uint8 SDLCALL SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, bool validDomain); /** * Returns a random boundary value for Uint16 within the given boundaries. @@ -171,10 +166,10 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint16BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint16BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint16BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint16BoundaryValue(0, 0xFFFF, SDL_FALSE) returns 0 (error set) + * RandomUint16BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint16BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint16BoundaryValue(0, 99, false) returns 100 + * RandomUint16BoundaryValue(0, 0xFFFF, false) returns 0 (error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -182,7 +177,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain); +Uint16 SDLCALL SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, bool validDomain); /** * Returns a random boundary value for Uint32 within the given boundaries. @@ -192,10 +187,10 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint32BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint32BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint32BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint32BoundaryValue(0, 0xFFFFFFFF, SDL_FALSE) returns 0 (with error set) + * RandomUint32BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint32BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint32BoundaryValue(0, 99, false) returns 100 + * RandomUint32BoundaryValue(0, 0xFFFFFFFF, false) returns 0 (with error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -203,7 +198,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain); +Uint32 SDLCALL SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, bool validDomain); /** * Returns a random boundary value for Uint64 within the given boundaries. @@ -213,10 +208,10 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomUint64BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20 - * RandomUint64BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21 - * RandomUint64BoundaryValue(0, 99, SDL_FALSE) returns 100 - * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, SDL_FALSE) returns 0 (with error set) + * RandomUint64BoundaryValue(10, 20, true) returns 10, 11, 19 or 20 + * RandomUint64BoundaryValue(1, 20, false) returns 0 or 21 + * RandomUint64BoundaryValue(0, 99, false) returns 100 + * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, false) returns 0 (with error set) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -224,7 +219,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL * * \returns a random boundary value for the given range and domain or 0 with error set */ -Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain); +Uint64 SDLCALL SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, bool validDomain); /** * Returns a random boundary value for Sint8 within the given boundaries. @@ -234,10 +229,10 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint8BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint8BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint8BoundaryValue(SINT8_MIN, 99, SDL_FALSE) returns 100 - * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, SDL_FALSE) returns SINT8_MIN (== error value) with error set + * RandomSint8BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint8BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint8BoundaryValue(SINT8_MIN, 99, false) returns 100 + * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, false) returns SINT8_MIN (== error value) with error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -245,8 +240,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT8_MIN with error set */ -Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain); - +Sint8 SDLCALL SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, bool validDomain); /** * Returns a random boundary value for Sint16 within the given boundaries. @@ -256,10 +250,10 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint16BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint16BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint16BoundaryValue(SINT16_MIN, 99, SDL_FALSE) returns 100 - * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, SDL_FALSE) returns SINT16_MIN (== error value) with error set + * RandomSint16BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint16BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint16BoundaryValue(SINT16_MIN, 99, false) returns 100 + * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, false) returns SINT16_MIN (== error value) with error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -267,7 +261,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo * * \returns a random boundary value for the given range and domain or SINT16_MIN with error set */ -Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain); +Sint16 SDLCALL SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, bool validDomain); /** * Returns a random boundary value for Sint32 within the given boundaries. @@ -277,10 +271,10 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint32BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint32BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint32BoundaryValue(SINT32_MIN, 99, SDL_FALSE) returns 100 - * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, SDL_FALSE) returns SINT32_MIN (== error value) + * RandomSint32BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint32BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint32BoundaryValue(SINT32_MIN, 99, false) returns 100 + * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, false) returns SINT32_MIN (== error value) * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -288,7 +282,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT32_MIN with error set */ -Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain); +Sint32 SDLCALL SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, bool validDomain); /** * Returns a random boundary value for Sint64 within the given boundaries. @@ -298,10 +292,10 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL * If boundary1 > boundary2, the values are swapped * * Usage examples: - * RandomSint64BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20 - * RandomSint64BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9 - * RandomSint64BoundaryValue(SINT64_MIN, 99, SDL_FALSE) returns 100 - * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, SDL_FALSE) returns SINT64_MIN (== error value) and error set + * RandomSint64BoundaryValue(-10, 20, true) returns -11, -10, 19 or 20 + * RandomSint64BoundaryValue(-100, -10, false) returns -101 or -9 + * RandomSint64BoundaryValue(SINT64_MIN, 99, false) returns 100 + * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, false) returns SINT64_MIN (== error value) and error set * * \param boundary1 Lower boundary limit * \param boundary2 Upper boundary limit @@ -309,8 +303,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL * * \returns a random boundary value for the given range and domain or SINT64_MIN with error set */ -Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain); - +Sint64 SDLCALL SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, bool validDomain); /** * Returns integer in range [min, max] (inclusive). @@ -323,8 +316,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL * * \returns a generated random integer in range */ -Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); - +Sint32 SDLCALL SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); /** * Generates random null-terminated string. The minimum length for @@ -335,8 +327,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); * * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated. */ -char *SDLTest_RandomAsciiString(void); - +char * SDLCALL SDLTest_RandomAsciiString(void); /** * Generates random null-terminated string. The maximum length for @@ -349,8 +340,7 @@ char *SDLTest_RandomAsciiString(void); * * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated. */ -char *SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); - +char * SDLCALL SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); /** * Generates random null-terminated string. The length for @@ -363,14 +353,14 @@ char *SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); * * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated. */ -char *SDLTest_RandomAsciiStringOfSize(int size); +char * SDLCALL SDLTest_RandomAsciiStringOfSize(int size); /** * Get the invocation count for the fuzzer since last ...FuzzerInit. * * \returns the invocation count. */ -int SDLTest_GetFuzzerInvocationCount(void); +int SDLCALL SDLTest_GetFuzzerInvocationCount(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h b/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h index 263071fbd..cea0db465 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_harness.h @@ -36,13 +36,15 @@ #ifndef SDL_test_h_arness_h #define SDL_test_h_arness_h +#include +#include /* SDLTest_CommonState */ + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /* ! Definitions for test case structures */ #define TEST_ENABLED 1 #define TEST_DISABLED 0 @@ -61,13 +63,13 @@ extern "C" { #define TEST_RESULT_SETUP_FAILURE 4 /* !< Function pointer to a test case setup function (run before every test) */ -typedef void (*SDLTest_TestCaseSetUpFp)(void *arg); +typedef void (SDLCALL *SDLTest_TestCaseSetUpFp)(void **arg); /* !< Function pointer to a test case function */ -typedef int (*SDLTest_TestCaseFp)(void *arg); +typedef int (SDLCALL *SDLTest_TestCaseFp)(void *arg); /* !< Function pointer to a test case teardown function (run after every test) */ -typedef void (*SDLTest_TestCaseTearDownFp)(void *arg); +typedef void (SDLCALL *SDLTest_TestCaseTearDownFp)(void *arg); /* * Holds information about a single test case. @@ -99,29 +101,48 @@ typedef struct SDLTest_TestSuiteReference { /* - * Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z). + * Generates a random run seed string for the harness. The generated seed + * will contain alphanumeric characters (0-9A-Z). * - * Note: The returned string needs to be deallocated by the caller. + * \param buffer Buffer in which to generate the random seed. Must have a capacity of at least length + 1 characters. + * \param length Number of alphanumeric characters to write to buffer, must be >0 * - * \param length The length of the seed string to generate - * - * \returns the generated seed string + * \returns A null-terminated seed string and equal to the in put buffer on success, NULL on failure */ -char *SDLTest_GenerateRunSeed(const int length); +char * SDLCALL SDLTest_GenerateRunSeed(char *buffer, int length); /* - * Execute a test suite using the given run seed and execution key. + * Holds information about the execution of test suites. + * */ +typedef struct SDLTest_TestSuiteRunner SDLTest_TestSuiteRunner; + +/* + * Create a new test suite runner, that will execute the given test suites. + * It will register the harness cli arguments to the common SDL state. * - * \param testSuites Suites containing the test case. - * \param userRunSeed Custom run seed provided by user, or NULL to autogenerate one. - * \param userExecKey Custom execution key provided by user, or 0 to autogenerate one. - * \param filter Filter specification. NULL disables. Case sensitive. - * \param testIterations Number of iterations to run each test case. + * \param state Common SDL state on which to register CLI arguments. + * \param testSuites NULL-terminated test suites containing test cases. * * \returns the test run result: 0 when all tests passed, 1 if any tests failed. */ -int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations); +SDLTest_TestSuiteRunner * SDLCALL SDLTest_CreateTestSuiteRunner(SDLTest_CommonState *state, SDLTest_TestSuiteReference *testSuites[]); +/* + * Destroy a test suite runner. + * It will unregister the harness cli arguments to the common SDL state. + * + * \param runner The runner that should be destroyed. + */ +void SDLCALL SDLTest_DestroyTestSuiteRunner(SDLTest_TestSuiteRunner *runner); + +/* + * Execute a test suite, using the configured run seed, execution key, filter, etc. + * + * \param runner The runner that should be executed. + * + * \returns the test run result: 0 when all tests passed, 1 if any tests failed. + */ +int SDLCALL SDLTest_ExecuteTestSuiteRunner(SDLTest_TestSuiteRunner *runner); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_log.h b/Source/ThirdParty/SDL/SDL3/SDL_test_log.h index 315d0ae0e..ff798d633 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_log.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_log.h @@ -36,6 +36,8 @@ #ifndef SDL_test_log_h_ #define SDL_test_log_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -47,14 +49,24 @@ extern "C" { * * \param fmt Message to be logged */ -void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Prints given prefix and buffer. + * Non-printible characters in the raw data are substituted by printible alternatives. + * + * \param prefix Prefix message. + * \param buffer Raw data to be escaped. + * \param size Number of bytes in buffer. + */ +void SDLCALL SDLTest_LogEscapedString(const char *prefix, const void *buffer, size_t size); /** * Prints given message with a timestamp in the TEST category and the ERROR priority. * * \param fmt Message to be logged */ -void SDLTest_LogError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +void SDLCALL SDLTest_LogError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h b/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h index 06a6272bd..d751aab96 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_md5.h @@ -56,6 +56,8 @@ #ifndef SDL_test_md5_h_ #define SDL_test_md5_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -65,15 +67,15 @@ extern "C" { /* ------------ Definitions --------- */ /* typedef a 32-bit type */ - typedef Uint32 MD5UINT4; +typedef Uint32 MD5UINT4; /* Data structure for MD5 (Message-Digest) computation */ - typedef struct SDLTest_Md5Context { - MD5UINT4 i[2]; /* number of _bits_ handled mod 2^64 */ - MD5UINT4 buf[4]; /* scratch buffer */ - unsigned char in[64]; /* input buffer */ +typedef struct SDLTest_Md5Context { + MD5UINT4 i[2]; /* number of _bits_ handled mod 2^64 */ + MD5UINT4 buf[4]; /* scratch buffer */ + unsigned char in[64]; /* input buffer */ unsigned char digest[16]; /* actual digest after Md5Final call */ - } SDLTest_Md5Context; +} SDLTest_Md5Context; /* ---------- Function Prototypes ------------- */ @@ -86,8 +88,7 @@ extern "C" { * mdContext. Call before each new use of the context - * all fields are set to zero. */ - void SDLTest_Md5Init(SDLTest_Md5Context *mdContext); - +void SDLCALL SDLTest_Md5Init(SDLTest_Md5Context *mdContext); /** * update digest from variable length data @@ -99,12 +100,10 @@ extern "C" { * Note: The function updates the message-digest context to account * for the presence of each of the characters inBuf[0..inLen-1] * in the message whose digest is being computed. -*/ - - void SDLTest_Md5Update(SDLTest_Md5Context *mdContext, unsigned char *inBuf, + */ +void SDLCALL SDLTest_Md5Update(SDLTest_Md5Context *mdContext, unsigned char *inBuf, unsigned int inLen); - /** * complete digest computation * @@ -113,10 +112,8 @@ extern "C" { * Note: The function terminates the message-digest computation and * ends with the desired message digest in mdContext.digest[0..15]. * Always call before using the digest[] variable. -*/ - - void SDLTest_Md5Final(SDLTest_Md5Context *mdContext); - + */ +void SDLCALL SDLTest_Md5Final(SDLTest_Md5Context *mdContext); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h b/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h index 6d858efdf..16b2f6330 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_test_memory.h @@ -30,34 +30,34 @@ #ifndef SDL_test_memory_h_ #define SDL_test_memory_h_ +#include + #include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus extern "C" { #endif - /** * Start tracking SDL memory allocations * * \note This should be called before any other SDL functions for complete tracking coverage */ -void SDLTest_TrackAllocations(void); +void SDLCALL SDLTest_TrackAllocations(void); /** * Fill allocations with random data * * \note This implicitly calls SDLTest_TrackAllocations() */ -void SDLTest_RandFillAllocations(); +void SDLCALL SDLTest_RandFillAllocations(void); /** * Print a log of any outstanding allocations * * \note This can be called after SDL_Quit() */ -void SDLTest_LogAllocations(void); - +void SDLCALL SDLTest_LogAllocations(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Source/ThirdParty/SDL/SDL3/SDL_thread.h b/Source/ThirdParty/SDL/SDL3/SDL_thread.h index f6ec760c4..f21356544 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_thread.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_thread.h @@ -34,9 +34,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -90,9 +89,9 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * 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.0.0. */ @@ -252,10 +251,10 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_PropertiesID props); -#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "entry_function" -#define SDL_PROP_THREAD_CREATE_NAME_STRING "name" -#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "userdata" -#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "stacksize" +#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "SDL.thread.create.entry_function" +#define SDL_PROP_THREAD_CREATE_NAME_STRING "SDL.thread.create.name" +#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "SDL.thread.create.userdata" +#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "SDL.thread.create.stacksize" /* end wiki documentation for macros that are meant to look like functions. */ #endif @@ -263,7 +262,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -320,10 +319,10 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S #define SDL_CreateThread(fn, name, data) SDL_CreateThreadRuntime((fn), (name), (data), (SDL_FunctionPointer) (SDL_BeginThreadFunction), (SDL_FunctionPointer) (SDL_EndThreadFunction)) #define SDL_CreateThreadWithProperties(props) SDL_CreateThreadWithPropertiesRuntime((props), (SDL_FunctionPointer) (SDL_BeginThreadFunction), (SDL_FunctionPointer) (SDL_EndThreadFunction)) -#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "entry_function" -#define SDL_PROP_THREAD_CREATE_NAME_STRING "name" -#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "userdata" -#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "stacksize" +#define SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER "SDL.thread.create.entry_function" +#define SDL_PROP_THREAD_CREATE_NAME_STRING "SDL.thread.create.name" +#define SDL_PROP_THREAD_CREATE_USERDATA_POINTER "SDL.thread.create.userdata" +#define SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER "SDL.thread.create.stacksize" #endif @@ -381,12 +380,12 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. @@ -504,8 +503,8 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * @@ -513,7 +512,7 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC int SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_time.h b/Source/ThirdParty/SDL/SDL3/SDL_time.h index de71506f3..eb73f7a7f 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_time.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_time.h @@ -95,24 +95,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +123,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +138,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -181,8 +181,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * * \param year the year. * \param month the month [1-12]. - * \returns the number of days in the requested month or a negative error code - * on failure; call SDL_GetError() for more information. + * \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.0.0. */ @@ -194,8 +194,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \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 a negative error - * code on failure; call SDL_GetError() for more information. + * \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.0.0. */ @@ -207,9 +207,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \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 a - * negative error code on failure; call SDL_GetError() for more - * information. + * \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.0.0. */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_timer.h b/Source/ThirdParty/SDL/SDL3/SDL_timer.h index 1c7ccff48..fa8b2bb22 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_timer.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_timer.h @@ -160,8 +160,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -224,8 +222,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -263,14 +259,14 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC int SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_touch.h b/Source/ThirdParty/SDL/SDL3/SDL_touch.h index 6889f3697..2b07d2d32 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_touch.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_touch.h @@ -31,7 +31,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_version.h b/Source/ThirdParty/SDL/SDL3/SDL_version.h index c0f518d4a..09b010dc0 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_version.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_version.h @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -63,7 +62,7 @@ extern "C" { * * \since This macro is available since SDL 3.0.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 3 /** * This macro turns the version numbers into a numeric value. diff --git a/Source/ThirdParty/SDL/SDL3/SDL_video.h b/Source/ThirdParty/SDL/SDL3/SDL_video.h index 97844ef29..4310f03e3 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_video.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_video.h @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -41,8 +62,25 @@ extern "C" { #endif - +/** + * This is a unique ID for a display for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the display is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.0.0. + */ typedef Uint32 SDL_DisplayID; + +/** + * This is a unique ID for a window. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.0.0. + */ typedef Uint32 SDL_WindowID; /* Global video properties... */ @@ -222,12 +260,60 @@ typedef intptr_t SDL_EGLAttrib; typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * 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.0.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.0.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -248,31 +334,31 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); */ typedef enum SDL_GLattr { - SDL_GL_RED_SIZE, - SDL_GL_GREEN_SIZE, - SDL_GL_BLUE_SIZE, - SDL_GL_ALPHA_SIZE, - SDL_GL_BUFFER_SIZE, - SDL_GL_DOUBLEBUFFER, - SDL_GL_DEPTH_SIZE, - SDL_GL_STENCIL_SIZE, - SDL_GL_ACCUM_RED_SIZE, - SDL_GL_ACCUM_GREEN_SIZE, - SDL_GL_ACCUM_BLUE_SIZE, - SDL_GL_ACCUM_ALPHA_SIZE, - SDL_GL_STEREO, - SDL_GL_MULTISAMPLEBUFFERS, - SDL_GL_MULTISAMPLESAMPLES, - SDL_GL_ACCELERATED_VISUAL, - SDL_GL_RETAINED_BACKING, - SDL_GL_CONTEXT_MAJOR_VERSION, - SDL_GL_CONTEXT_MINOR_VERSION, - SDL_GL_CONTEXT_FLAGS, - SDL_GL_CONTEXT_PROFILE_MASK, - SDL_GL_SHARE_WITH_CURRENT_CONTEXT, - SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, - SDL_GL_CONTEXT_RESET_NOTIFICATION, + SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ + SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ + SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 2. */ + SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. */ + SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */ + SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */ + SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */ + SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */ + SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */ + SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */ + SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */ + SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */ + SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */ + SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */ + SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ + SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ + SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ + SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM @@ -331,8 +417,7 @@ typedef enum SDL_GLContextResetNotification /** * Get the number of video drivers compiled into SDL. * - * \returns a number >= 1 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns the number of built in video drivers. * * \since This function is available since SDL 3.0.0. * @@ -459,15 +544,15 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -483,15 +568,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SD * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -582,15 +667,15 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * the search. * \param mode a pointer filled in with the closest display mode equal to or * larger than the desired mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC int SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *mode); /** * Get information about the desktop's display mode. @@ -727,16 +812,16 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -744,7 +829,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -1053,39 +1138,40 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_PropertiesID props); -#define SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "always_on_top" -#define SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN "borderless" -#define SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN "focusable" -#define SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN "external_graphics_context" -#define SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN "fullscreen" -#define SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER "height" -#define SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN "hidden" -#define SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN "high_pixel_density" -#define SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN "maximized" -#define SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN "menu" -#define SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN "metal" -#define SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN "minimized" -#define SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN "modal" -#define SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN "mouse_grabbed" -#define SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN "opengl" -#define SDL_PROP_WINDOW_CREATE_PARENT_POINTER "parent" -#define SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN "resizable" -#define SDL_PROP_WINDOW_CREATE_TITLE_STRING "title" -#define SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN "transparent" -#define SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN "tooltip" -#define SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN "utility" -#define SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN "vulkan" -#define SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER "width" -#define SDL_PROP_WINDOW_CREATE_X_NUMBER "x" -#define SDL_PROP_WINDOW_CREATE_Y_NUMBER "y" -#define SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER "cocoa.window" -#define SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER "cocoa.view" -#define SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "wayland.surface_role_custom" -#define SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN "wayland.create_egl_window" -#define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER "wayland.wl_surface" -#define SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER "win32.hwnd" -#define SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER "win32.pixel_format_hwnd" -#define SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER "x11.window" +#define SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "SDL.window.create.always_on_top" +#define SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN "SDL.window.create.borderless" +#define SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN "SDL.window.create.focusable" +#define SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN "SDL.window.create.external_graphics_context" +#define SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER "SDL.window.create.flags" +#define SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN "SDL.window.create.fullscreen" +#define SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER "SDL.window.create.height" +#define SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN "SDL.window.create.hidden" +#define SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN "SDL.window.create.high_pixel_density" +#define SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN "SDL.window.create.maximized" +#define SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN "SDL.window.create.menu" +#define SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN "SDL.window.create.metal" +#define SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN "SDL.window.create.minimized" +#define SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN "SDL.window.create.modal" +#define SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN "SDL.window.create.mouse_grabbed" +#define SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN "SDL.window.create.opengl" +#define SDL_PROP_WINDOW_CREATE_PARENT_POINTER "SDL.window.create.parent" +#define SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN "SDL.window.create.resizable" +#define SDL_PROP_WINDOW_CREATE_TITLE_STRING "SDL.window.create.title" +#define SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN "SDL.window.create.transparent" +#define SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN "SDL.window.create.tooltip" +#define SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN "SDL.window.create.utility" +#define SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN "SDL.window.create.vulkan" +#define SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER "SDL.window.create.width" +#define SDL_PROP_WINDOW_CREATE_X_NUMBER "SDL.window.create.x" +#define SDL_PROP_WINDOW_CREATE_Y_NUMBER "SDL.window.create.y" +#define SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER "SDL.window.create.cocoa.window" +#define SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER "SDL.window.create.cocoa.view" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "SDL.window.create.wayland.surface_role_custom" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN "SDL.window.create.wayland.create_egl_window" +#define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER "SDL.window.create.wayland.wl_surface" +#define SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER "SDL.window.create.win32.hwnd" +#define SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER "SDL.window.create.win32.pixel_format_hwnd" +#define SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER "SDL.window.create.x11.window" /** * Get the numeric ID of a window. @@ -1198,11 +1284,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1269,7 +1350,6 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" @@ -1310,14 +1390,14 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1341,17 +1421,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * 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 size image will be scaled to the appropriate size - * and be used instead. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. @@ -1383,15 +1464,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surfac * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1407,14 +1488,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. @@ -1441,8 +1522,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1450,7 +1531,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1462,8 +1543,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1471,7 +1552,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1486,12 +1567,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, in * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1522,15 +1603,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Re * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1540,19 +1621,19 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, flo * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * 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. * @@ -1562,7 +1643,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, flo * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * 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. @@ -1574,14 +1656,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, flo * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1591,15 +1673,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1607,15 +1689,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, in * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1625,15 +1707,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1641,15 +1723,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1659,15 +1741,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1679,15 +1761,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1699,15 +1781,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bo * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1716,43 +1798,42 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_b * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_ShowWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1765,12 +1846,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1793,8 +1874,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1802,7 +1883,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window); * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. @@ -1817,8 +1898,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1826,7 +1907,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window); * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be @@ -1842,8 +1923,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1851,7 +1932,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window); * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1870,10 +1951,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * @@ -1881,7 +1961,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window); * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1897,9 +1977,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_ * * \param window the window for which to wait for the pending state to be * applied. - * \returns 0 on success, a positive value if the operation timed out before - * the window was in the requested state, or a negative error code on - * failure; call SDL_GetError() for more information. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * * \since This function is available since SDL 3.0.0. * @@ -1911,20 +1990,20 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_ * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC int SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1968,14 +2047,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -1986,14 +2065,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, in * \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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2004,15 +2083,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, in * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2031,29 +2110,29 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2075,16 +2154,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2092,40 +2171,40 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SD * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * * \since This function is available since SDL 3.0.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. @@ -2148,15 +2227,15 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowMouseRect * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2177,18 +2256,18 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2197,8 +2276,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float o * 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 a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on + * failure; call SDL_GetError() for more information. * * \since This function is available since SDL 3.0.0. * @@ -2207,36 +2286,58 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float o extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * 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. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModalFor() to cancel the modal status + * before attempting to change the parent. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * 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. * * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_SetWindowParent + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \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. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2255,12 +2356,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_b * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. @@ -2318,7 +2419,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return -1 + * 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 @@ -2332,12 +2433,12 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. @@ -2356,24 +2457,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_Hit * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. @@ -2399,28 +2500,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * * \since This function is available since SDL 3.0.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC int SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2431,15 +2531,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC int SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2459,15 +2559,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2563,11 +2663,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. @@ -2590,15 +2690,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); /** * Get the actual value for an attribute from the current context. @@ -2606,15 +2706,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2645,14 +2745,14 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2711,27 +2811,23 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * 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. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2741,8 +2837,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return -1. In such a case, you should probably - * retry the call with 1 for the interval. + * 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 @@ -2753,14 +2849,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2772,14 +2868,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); * 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 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2792,25 +2888,25 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC int SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Source/ThirdParty/SDL/SDL3/SDL_vulkan.h b/Source/ThirdParty/SDL/SDL3/SDL_vulkan.h index 6dd05375f..6c777749e 100644 --- a/Source/ThirdParty/SDL/SDL3/SDL_vulkan.h +++ b/Source/ThirdParty/SDL/SDL3/SDL_vulkan.h @@ -28,6 +28,7 @@ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -95,15 +96,15 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -175,18 +176,18 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \since This function is available since SDL 3.0.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, - VkInstance instance, - const struct VkAllocationCallbacks *allocator, - VkSurfaceKHR* surface); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, + VkInstance instance, + const struct VkAllocationCallbacks *allocator, + VkSurfaceKHR* surface); /** * Destroy the Vulkan rendering surface of a window. @@ -226,14 +227,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * * \since This function is available since SDL 3.0.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs index 17a40709c..0cfc365d7 100644 --- a/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs +++ b/Source/Tools/Flax.Build/Deps/Dependencies/SDL.cs @@ -73,7 +73,7 @@ namespace Flax.Deps.Dependencies "-DSDL_SNDIO=OFF", "-DSDL_PULSEAUDIO=OFF", "-DSDL_ALSA=OFF", - "-DSDL_WASAPI=OFF", + "-DSDL_GPU=OFF", }; var filesToKeep = new[] { @@ -88,8 +88,8 @@ namespace Flax.Deps.Dependencies Path.Combine(root, "include", "SDL3"), }; - CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL.git", new DateTime(2024, 8, 5)); - GitResetToCommit(root, "627cb8acd09e6cbf8362d808634a26f37382c73d"); + CloneGitRepoFastSince(root, "https://github.com/libsdl-org/SDL.git", new DateTime(2024, 10, 1)); + GitResetToCommit(root, "e292d1f5ace469f718d7b6b4dec8c28e37dcaa0e"); foreach (var platform in options.Platforms) {